01
経路は三つ、失敗の仕方も三通りです
宣言済みの画像フィールドは、公開 HTTPS URL、コミット済みの spicy:// ファイル URI、インライン data URI を受け取ります。インラインは一枚あたりデコード後 1 MiB・8,388,608 ピクセル、本文全体で 2 MiB までです。それを超えるならアップロードチケットを使います。
編集 API ソリューション
モデルが想像した絵ではなく、手元の絵を編集する。
編集エンドポイントは少なくとも二つの入力を取ります。画像と指示です。その画像を届ける手段（公開 URL、コミット済みアップロード、インライン data URI）でつまずく実装がほとんどです。
解決する課題
難しいのは参照画像を届ける側
プロンプトは簡単なほうです。もう一方は利用者の端末にあるファイルで、非公開バケットを露出させずにモデルへ届き、タスク成立前に検査される上限に収まる必要があります。
02
取得できる署名付き HTTPS URL は使用できます
署名付きリンクで Cookie や別途ログインなしに取得できれば、非公開バケットの画像も参照できます。処理中は有効にしてください。プライベート IP、ループバック、user:password 形式の認証情報は拒否されます。
03
編集は生成とは別のタスクです
公開呼び出し名は /edit で終わり、スキーマは通常 image_url または image_urls を必須にし、mask_url や strength を加えるものもあります。text-to-image の model 値を編集フローに入れると、緩やかに劣化せず検証で失敗します。
実装方針
一度アップロードし、コミットし、ファイル URI を参照する
利用者のファイルはアップロードチケットを取得し、宣言したバイト数ちょうどを返却ヘッダーごと PUT し、コミットしてから、返ってきた spicy:// URI をモデルの画像フィールドに渡します。以後その参照はアカウントに属し、検査は一度で済み、再アップロードなしに複数タスクで使えます。
チケット、PUT、コミット、作成。すでに公開されているメディアは最初の三手を飛ばせます。
Ticket → PUT → commit → create
POST /api/v1/common/upload-url
{ "contentType": "image/png", "bytes": 482113 }
→ { "fileId": "fil_01k3…", "uploadUrl": "https://…", "method": "PUT", "headers": { … } }
PUT <uploadUrl> # exactly 482113 bytes, every returned header replayed
POST /api/v1/files/fil_01k3…/commit
→ { "status": "ready", "uri": "spicy://f/fil_01k3…", "sha256": "…" }POST /api/v1/jobs/createTask
{
"model": "<publisher>/<model>/edit",
"input": {
"prompt": "Replace the background with an overcast beach at dusk",
"image_urls": ["spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"]
}
}契約
先に押さえておく項目
| フィールド / ヘッダー | 値・上限 |
|---|---|
| POST /api/v1/common/upload-url | JPEG · PNG · WebP · GIF ≤ 10 MiB |
| POST /api/v1/files/{fileId}/commit | returns spicy://f/fil_… |
| inline data URI | ≤ 1 MiB decoded · ≤ 8192 px per side |
| request body | ≤ 2 MiB · ≤ 16 images |
横にスワイプして全項目を確認できます。
導入
最初の呼び出しから本番まで
- 01POST /api/v1/common/upload-url に contentType と正確なバイト数を送ります。JPEG・PNG・WebP・GIF は 10 MiB まで。
- 02チケットが返したヘッダーをすべて付けて署名付き URL へ PUT し、POST /api/v1/files/{fileId}/commit を呼びます。
- 03そのエンドポイントの編集用 model 値で createTask を送り、spicy:// URI を image_url か image_urls に入れます。
- 04コールバックまたは recordInfo から output.assets を読み、編集後のファイルを自分で保存します。
向き不向き
この方法が向いている場面
こんなときに選ぶ
- 利用者の写真から始まるプロダクト。レタッチ、背景差し替え、作風変更、不要物除去など。
- 同じ参照を複数タスクで使い回し、毎回アップロードし直したくない場合。
こんなときは別の方法へ
- 元画像がない場合。text-to-image のほうが安く、契約も単純です。
- コマ単位の動画編集が必要な場合。編集エンドポイントが返すのは静止画です。
裏付け
自分で確認できること
アップロードはアカウント紐付けで、コミット時に検査されます
コミットは保存されたバイト数とメディアタイプをチケットと突き合わせ、画像シグネチャを検証し、SHA-256 を計算します。それを通って初めて参照可能になります。
インライン画像はレコードに戻りません
data URI はアカウント紐付けのファイルとして保存されます。recordInfo が返す正規化済み入力に入るのはファイル URI で、元の Base64 バイトではありません。
素材と成果物は別の時計で動きます
アップロードした素材は 1 日、生成結果は 14 日保持されます。どちらも公開値で、アカウントごとの交渉事項ではありません。
公開前に
確認しておくプラットフォームの挙動
- 元画像の権利を誰が確認するかを決めます。プラットフォームは代わりに検査しません。
- チケットを要求する前にクライアント側でメディアタイプとサイズを検証します。413 は処理するより避けるほうが安上がりです。
- 同じ元画像を再編集する予定があるなら、spicy:// URI を自分のレコードに残します。
- invalid_asset は障害ではなく、利用者に見せるエラーとして扱います。
よくある質問
このページでよく聞かれること
どちらでも構いません。公開到達可能な HTTPS メディア URL はそのまま画像フィールドに入ります。アップロードチケットは非公開ファイルと、インライン上限を超えるファイルのためにあります。
一枚あたりデコード後 1 MiB と 8,388,608 ピクセル、一辺 8192 ピクセルまで、合計 16 枚・16,777,216 ピクセルまで、本文全体で 2 MiB までです。
参照の検証は受理段階で行われます。到達不能ホスト、プライベートアドレス、非対応のメディアタイプ、過大なファイルは、タスクが存在する前に 400 か 413 で失敗します。保留も課金も発生しません。
エンドポイント次第です。同一性のための参照画像フィールドを明示的に宣言しているものもあり、受け取れる内容と枚数はモデルページに記載されています。
モデル
この用途で呼び出せるモデル
各リンクはそのモデルシリーズのページに移動します。入力、上限、コンテンツ方針、単位あたりの現在価格をそこで確認できます。
