画像編集
画像 API で画像の編集、マスクによるインペイント、バリエーション生成を行います。
概要
画像 API は既存の画像を 3 つの方法で編集します：整画像編集、マスクベースのインペイント、バリエーションです。いずれのモードもソース画像（および任意のマスク）をアップロード済み素材として受け取ります — URL 通路もインライン通路もありません。
警告
/v1/images/edits と /v1/images/variations は application/json のみを受け付けます。レガシーの multipart/form-data ファイルアップロードは削除されました — multipart を送ると 415 legacy_multipart_removed を返します。画像が数 KB でも 25 MB でも、ソースとマスクはまず presigned アップロードを経由し、その後 image_upload_id / mask_upload_id を含む JSON を送信します。
3 つのモード
| モード | エンドポイント | 必須 | 効果 |
|---|---|---|---|
| 整画像編集 | POST /v1/images/edits | model、prompt、image_upload_id | プロンプトに従って画像全体を編集 |
| マスクインペイント | POST /v1/images/edits | 上記 + mask_upload_id | マスクされた領域のみを変更 |
| バリエーション | POST /v1/images/variations | model、image_upload_id（prompt 不要） | 同じスタイルのバリエーションを生成 |
mask_upload_id を渡すと、編集は自動的にインペイントに切り替わります — 追加のフラグは不要です。
画像を編集する
まずpresign してアップロードし、ソースを purpose=image_edit_source で（インペイントの場合はマスクを purpose=image_edit_mask で）アップロードします。その後 JSON を送信します：
| 1 | curl https://api.alltoken.ai/v1/images/edits -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "prompt": "Change the background to a sunset", |
| 4 | "image_upload_id": "upl_source...", |
| 5 | "mask_upload_id": "upl_mask...", |
| 6 | "size": "1024x1024", |
| 7 | "output_format": "png" |
| 8 | }' |
よく使う任意フィールド：size、quality、output_format、output_compression、background、moderation、n、user。完全なリストは 画像 API リファレンス を参照してください。
バリエーションを生成する
バリエーションはソース（purpose=image_variation_source でアップロード）のみが必要で、prompt は不要です：
| 1 | curl https://api.alltoken.ai/v1/images/variations -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "image_upload_id": "upl_source...", |
| 4 | "n": 2 |
| 5 | }' |
任意フィールド：size、n、output_compression、user。
結果を取得する
作成すると 202 + { id, status: "queued", ... } が返ります。3 つのモードすべてが同じエンドポイントをポーリングします：
$curl https://api.alltoken.ai/v1/images/generations/{id} -H "Authorization: Bearer $ALLTOKEN_API_KEY"queued / processing の間、レスポンスには next_poll_after_ms が含まれます — これを使って次回ポーリングの間隔を調整してください。completed になると、各 data[] 項目に b64_json、r2_url、r2_url_expires_at、mime_type、revised_prompt が含まれます。
警告
b64_json は一度だけ提供されます — 最初の completed の GET のみが返すため、取得したらすぐにディスクへ書き込んでください。r2_url（30 日間有効、デバイス間でアクセス可能）を優先し、b64_json は初回取得のフォールバックとして扱ってください。r2_url の有効期限が切れると GET は 410 image_expired を返します。「画像一覧」エンドポイントはありません — 結果は task_id ごとに自分で記録してください。
バッチ編集
1 回のリクエストで1 枚のソース画像（および任意で 1 枚のマスク）を処理します。N 枚の画像を編集するには、N 回の独立した 3 ステップフローを実行します — それぞれが独自の presign → PUT → 作成 → ポーリングを行います。並行して実行できますが、2 つの制限に注意してください：
- pending アップロード 100 件 — 数百個の
upload_idを presign して未使用のまま放置しないでください。 - UTC の 1 日あたり 2 GiB — 25 MiB のファイル約 80 個で上限に達します。
推奨：5〜10 の並行レーンに抑え、各レーンは次の画像に移る前に presign → PUT → 作成 → ポーリングを完走させます。こうすれば pending 数は小さく保たれ、クォータに達することもありません。クォータの詳細は メディアアップロード を参照してください。