SpicyAPI（spicyapi.ai）のImage Expanderは、正方形の商品写真から横長のバナーと縦長のストーリーをすぐ作る手段です。画像を1枚とアスペクト比を1つ送ると、写真を大きなフレームの中に収めたうえで、周囲に新しい風景を描き込んで返します。選んだプロポーションにかかわらず、画像1枚あたり$0.024で、プロンプトもマスクも要りません。出力の長辺は常に1536 pxです。欠点は写真の一部も描き直されることで、背景として使うものには向きますが、製品の細部を正確に保てません。ピクセル単位で一致するパッケージが必要なら、元の写真を上に重ね直します。何を描くかを制御したい場合は、新しい比率のシーンをプロンプトベースの画像編集モデルで生成してください。同じ3つのフォーマットを扱った商品写真から広告レイアウトへのガイドがその方法を示します。
切り抜き、レイアウト、拡張のどれを選ぶか
- 切り抜くのは、必要な側にすでに余った風景があるときです。無料で、すべてのピクセルがそのまま残ります。
- キャンバスをデザインする（単一色、または写真の横のパネル）のは、見出しに確実にきれいな領域を確保したいときです。生成された風景ではこれを保証できません。
- 拡張するのは、目的のフォーマットが撮影時より多くの絵を必要とし、単一色だと不自然になるときです。縦の構図の上に空、正方形の横に天板と壁など。形の変化が控えめなほど自然に混ざります。元の形から離れるほど、想像される風景が増えていきます。
7つのプロポーションに対する出力サイズ
長辺は常に1536 pxで、短辺はプロポーションに従います。タスクはspicyapi/image-expander-v1/editで、次の値に対応します。
| プロポーション | 出力 | 主な用途 |
|---|---|---|
| 1:1 | 1536 × 1536 | フィード投稿、マーケットプレイスのタイル |
| 4:3 | 1536 × 1152 | スライド、プレゼンテーション |
| 3:4 | 1152 × 1536 | 縦長のフィード投稿 |
| 3:2 | 1536 × 1024 | 印刷風の横長、バナー |
| 2:3 | 1024 × 1536 | 印刷風の縦長、ピン |
| 16:9 | 1536 × 864 | サイトのヘッダー、動画のカバー |
| 9:16 | 864 × 1536 | ストーリー、リール |
計画上で重要な点が2つあります。まず、4:5と1.91:1は提供されません。3:4を使い、高さを96 px切って4:5（1152 × 1440）にするか、16:9を使い約60 px切って1.91:1（1536 × 804）にしてください。次に、元の画像は収まるように拡大縮小されるため、正方形写真からの16:9結果では、元の画像がどれほど大きくても製品の高さは最大864 pxです。より多くのピクセルが必要なら、品質の低い入力を出発点にせず、画像拡大ガイドのワークフローで完成画像をアップスケールしてください。
各切り替えが求める新しい風景の量
写真は目標のキャンバスに収まるよう1つの係数で拡大縮小され、残りはすべて描かれます。1200 × 1200の正方形なら、16:9でも9:16でも係数は0.72で、フレーム中央に864 × 864の写真が残り、672 pxの新しい風景（キャンバスの44%）ができます。16:9の写真を9:16にするのははるかに難しく、写真は864 × 486まで縮小され、フレームの68%が想像で埋まります。
大きな切り替えも動作します。公開済みの例では、1280 × 720のテラスポートレートを864 × 1536のフルレングスストーリー枠に広げ、残りの衣装、床タイル、空を描き込んでいます。
もうひとつは反対方向です。寄った2:3のポートレートは1536 × 864のヘッダーになり、暗い壁が左右にそのまま続きます。これはバナーに必要な見出しの余地そのものです。
モデルが写真に対して行うこと
Image Expanderの公開サンプルは、出力の使い方を左右する3つのことを示しています。
- 写真は枠に合わせて拡大縮小されるだけで、端に固定されるわけではありません。 テラス結果では上から462 px、下から588 pxの位置にあり、ポートレート結果では左から453 px、右から507 pxの位置にあります。どちらも写真がわずかに中心から外れるため、正確な中央配置を当てにせず、写真そのものを動かすこともできません。アンカー欄もパディング欄もありません。テキスト領域は左右の余った場所に置くか、反対側を切り取って製品を動かしてください。
- 写真自体も一部が描き直されます。 テラス結果では顔、髪、レモンの葉、右側の手摺が元画像と異なります（元画像領域内の平均ピクセル変化は、リサンプリングと圧縮の差を含めて255段階中30です）。場面は同じ撮影に見えますが、細部は生成し直されています。
- 縁が弱みです。 空、スタジオの背景、漆喰、砂が最も自然に続きます。境界で切られた顔、手、文字は想像するしかありません。
公開前に元画像と結果を比較してください。ロゴやラベルの領域でピクセル変化が大きいなら、その領域は元画像から用意する必要があります。実務上のルールは、結果を背景として使い、正確にしなければならない場面では本物の製品を上に重ね直すことです。ラベルのある袋やボトルには、背景除去ワークフローで元画像から製品を切り出し、レイアウトに必要なサイズで拡張したシーンに配置し、接触影を描き直してください。同じ3つのフォーマットについてレイアウトとラベル保護の手順は商品写真から広告レイアウトへのガイドが扱っているので、ここでは繰り返しません。
うまく拡張できる元画像を選ぶ
- 製品の周囲に余白を残し、拡張の起点になる境界から離してください。横に空間のある、完成状態の製品は、タイトな切り抜きより安全に拡張できます。
- シンプルな周囲を選びましょう：継ぎ目のない紙、漆喰の壁、空、地平線が1本だけのはっきりした線となる天板。タイルやストライプのような繰り返しパターンは、接合部で位相がずれることがあります。
- 最も近いプロポーションを選びます。 マーケットプレイスが5:4を望んでいるなら、9:16の元画像からではなく1:1か4:3から始めてください。
まずPlaygroundで試す
- Image Expanderのタスクページを開き、PlaygroundタブのForm表示のまま進みます。実行には残高のあるアカウントでサインインします。
- Input imageに写真をドロップするか、Asset URLへ直接リンクを貼り付けます（JPG、PNGまたはWebP、最大10 MB）。
- Aspect ratioで目的のフォーマットに合うプロポーションを選んでください（APIが受け付けないAutoは使いません）。たとえばヘッダーなら16:9、ストーリーなら9:16です。Output formatは既定でPNGです。ファイルサイズを小さくするならJPEGかWebPを選んでください。
- 価格の見積もりを確認してから実行します。必要なプロポーションを、まず最も難しい元画像で試してください。ここで接合の精度が悪ければ、API経由でも悪くなります。
フォームの下に表示されるリクエストボディは、APIが受け取るJSONとまったく同じです。ここで動く設定は、そのままコードに書き移せます。
続いてコードから呼び出す
Python SDK（pip install spicyapi）をインストールし、環境変数にSPICY_API_KEYを設定して、元画像とプロポーションごとに1回ずつ呼び出します：
import uuid
from spicyapi import SpicyClient, output_assets
client = SpicyClient() # reads SPICY_API_KEY from the environment
photo = client.upload_file("./product-square.png") # local files become spicy:// URIs
task = client.create_task(
model="spicyapi/image-expander-v1/edit",
input_data={"image_url": photo["uri"], "aspect_ratio": "9:16", "output_format": "png"},
idempotency_key=str(uuid.uuid4()), # new key per new request; reuse only to retry the same one
)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
raise RuntimeError(f"Task {task['taskId']} ended as {final['state']}")
print(output_assets(final)[0]["url"]) # copy it to your own storage nowアップロード、待機、エラー、再試行はPython SDKリファレンスと非同期タスクガイドにまとまっています。フォーマットを1つ追加するたびにaspect_ratioと冪等性キーを変更してください。課金されるのは成功したタスクだけです。
Agentに実行させる
フォーマットをアシスタントに作らせるなら、CLIかMCPサーバーを渡します。どちらも価格を表示し、有料の呼び出し前に確認を求めます。Skillはどちらにも指示を上乗せします。
- CLI.
spicyapiはターミナルやスクリプトから1つのタスクを実行します（npx @spicyapi/cliならインストールなしで動作します）。
``bash spicyapi files upload ./product-square.png # prints a spicy:// URI spicyapi tasks create --model spicyapi/image-expander-v1/edit \ --input-file input.json --idempotency-key product-square-9x16-v1 --wait ``
input.jsonには、上記と同じinputオブジェクトをspicy://のURIで記載します。
- MCPサーバー. アシスタントにMCPサーバーを追加し、"Expand ./product-square.png to 9:16 and 16:9 with Image Expander."と尋ねます。
spicyapi_upload_fileを呼び出し、次にspicyapi_task_create（価格の確認で停止します）、その後spicyapi_task_waitを呼び出します。
``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``
- Skill.
npx skills add spicyapi-ai/spicy-skillはAgent Skillをインストールし、コーディングアシスタントが推測せずに最新のスキーマを読み、冪等性キーを再利用できるようにします。単体ではタスクを実行できないため、CLIやMCPと合わせて使ってください。
3回のパスで結果を確認する
- 製品：点数、シルエット、色、ラベル、ハンドルやキャップが同じか。ロゴが変わった、あるいは新しい領域にマグカップが2つ現れたら、それはスタイル選択ではなく不合格です。
- 接合部：天板の縁、壁のパターン、地平線、光の向きを、元の境界の向こうまでたどってください。製品の後ろにある継ぎ目は問題ですが、あなたが切り落とす角の継ぎ目ではありません。
- レイアウト：見出しボックスとプラットフォームのオーバーレイ領域を重ねます。縦のストーリーではインターフェース操作の下に製品が隠れることがあるため、その配置での最新のセーフエリア指針を確認してください。
問題が切り抜き範囲の外にあるなら、そこを切り取ってください。製品やテキスト領域をまたいでいる場合は、元画像を変える（より広い元画像、より緩いフレーミング、より無地の背景）か、デザインしたキャンバスに戻ってください。同じ元画像での新しい生成は補修ではなく新しい引き直しなので、先に何かを変更してください。
3フォーマット一式の費用
完成した出力は1件あたり$0.024なので、同一の元画像から16:9と9:16を作ると2 x $0.024 = $0.048、3件（たとえば4:3の元画像から1:1、16:9、9:16）なら$0.072です。元画像20点を2つのプロポーションで処理すると40回、$0.96になります。5点がより良い元画像でもう1回必要なら45回、$1.08です。カットアウト、アップスケール、デザインの作業時間は含みません。完成したリクエストは結果の見た目にかかわらず課金されるため、再試行を無作為に繰り返すのではなく、実行前に元画像を直してください。
よくある質問
写真が1536 pxより大きい場合は？ 長辺1536 pxで返るため、元の画像より小さくなることがあります。用途でさらに多くのピクセルが必要なら、後からアップスケールしてください。
動画の9:16の最初のフレームに使えますか？ 人物とポーズがすでに完成していれば使えます。横長のポートレートを縦のAI動画に変換するガイドを参照してください。モデルページには最新のスキーマと価格があります。
