Pro API: 画像の生成とレタッチ

モードにかかわらず、1枚の画像につき 1 クレジット かかります。プロンプトからの生成も、アップロード画像のレタッチも、同じルートで処理されます。

POST /images/quote は同じリクエストボディを受け取り、何も作成せずに価格を返します。常に { "cost": 1, ... } が返ります。動画では価格が変動するため、その対称性のために用意されています。

画像を送信する

POST /images

{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
  "width": 832, "height": 1216 }

レスポンス:

{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }

seed はレスポンスに含まれて返されます。指定した場合も、ランダムに決定された場合も同様です。同じ画像を再生成したいとき、またはバリエーションを作りたいときのために保存しておいてください。

複数枚を一度にリクエストする

count を1より大きくすると、1回のリクエストで複数のレンダリングが開始され、それぞれ固有のシードが割り当てられます。レスポンスはその一覧を返します。

{ "count": 4, "requested": 4, "cost_total": 4,
  "jobs": [ { "jobId": "...", "seed": 178078967, "cost": 1 }, { "jobId": "...", "seed": 903412, "cost": 1 } ],
  "errors": [],
  "jobId": "...", "seed": 178078967, "cost": 1 }

注意すべき点が2つあります。

最初のレンダリングの jobId、seed、cost がトップレベルにも繰り返されています。これは、バッチ処理に対応する前に書かれたクライアントが変更なしに動作し続けるためのものであり、最初のジョブが特別というわけではありません。jobs の全エントリをポーリングしてください。

そして count と requested を必ず比較してください。クレジット不足やキーの1日上限到達などの理由でバッチが途中で止まることがあります。その場合、requested はリクエストした枚数、count は実際に開始された枚数を示し、errors に停止理由が記録されます。両者が等しいと仮定したクライアントは、レンダリングが欠けていても気づけません。

POST /images/quote も count を受け付け、バッチ全体の価格を算出します。動画には count がありません。1リクエストにつき1クリップです。

3つのレタッチモード

3つのモードはすべて同じ命令駆動の編集エンジンで動作し、ソース画像の見た目を保持します。ソース画像を指定した場合、width と height は画像自体から読み取られるため、送信不要です。

editでは、アプリと同じくサーバーがレタッチの最適な処理方法を自動で選びます。

• マスクあり：指示を読み取り、領域の内容を置き換える（別の物、別の服、顔：そこに現れるべきものに合わせて領域を描き直す）か、そこにあるものを変更する（色、素材、光）かを選びます。キャラクターのloraがあれば、領域は顔も含めて常に描き直されます。
• マスクなしでキャラクターのloraあり（"replace the woman with kara..."）：サーバーが写真の人物を見つけてキャラクターとして描き直します。人物が見つからない場合は、これまでどおり指示が画像全体に適用されます。

料金はどの場合も同じです（1画像につき1クレジット）。どちらが選ばれたかは結果に現れ、レスポンスには含まれません。

IMG=$(base64 -w0 photo.png)
curl -s $B/images -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{\"mode\":\"edit\",\"prompt\":\"add a red scarf, keep everything else identical\",\"image_b64\":\"$IMG\"}"

キャラクター、オブジェクト、ロケーションを使って画像を作成する

POST /images に multiref オブジェクトを追加すると、サーバーがあなたのキャラクター（キャラクター）、オブジェクトと動物、そしてロケーション（サブジェクト）を1枚の画像にまとめて登場させます。アプリの「Create an image」画面と同じように、それぞれが識別できる状態で描かれます。プロンプト内でそれぞれを @Name で呼び出してください（プロンプトは英語で）。

{ "prompt": "@Mia hands a cup of coffee to @Tom on a sunny terrace, both smiling",
  "multiref": {
    "characters": [
      { "character_id": "chr_8f3a...", "name": "Mia", "view": 1 },
      { "character_id": "chr_21bc...", "name": "Tom", "lora": "tom_v1", "strength": 1.0, "lora_pass": 0.55 }
    ],
    "subjects": [ { "subject_id": "sub_...", "name": "Mug" } ],
    "location": { "subject_id": "sub_...", "name": "Terrace" }
  },
  "width": 1344, "height": 768, "seed": 42, "count": 1 }

• サブジェクトは最大4件（キャラクター、オブジェクト、動物）。LoRAを使わず画像だけの場合は、ロケーションを含めて最大4件のリファレンスです。サーバーはリファレンスに応じて方式を選び、characters、次に subjects の順で、左から右へそれぞれを配置します。
• どのリファレンスにも一致しない @Name は拒否されます（unknown_mention）。プロンプトに出てこないリファレンスもそのまま送られます。
• 料金: 1パスの料金は画像1枚分（1 クレジット）です。シンプルな画像は1パス。複数のキャラクターをLoRAで描く場合は、1にLoRAごとに1パスを加えた数（最大4）。画像だけの場合は、最初のリファレンス以降、リファレンスごとに1パス。組み合わせた場合は、その両方です。合計（パス数 x count）は送信時に確保され、最終画像の時点で1回だけ差し引かれます。失敗やキャンセルの場合は料金がかかりません。同じボディで POST /images/quote を送ると、何も開始せずに正確な料金、方式、そのパスを返します。
• レスポンス 202: { "jobId": "mri_...", "seed", "cost", "method", "passes", "billed_passes" }（count が2の場合: jobs と cost_total）。ポーリング、ダウンロード、キャンセルは下記の通常のルートを使います。レンダリング中は progress が現在のパスを示します（"2/3"）。画像1枚に1〜3分かかります。
• 最終画像は1時間、そして最初のダウンロードから10分間利用できます。パスが失敗すると status: "failed" と reason: "render_failed" が返り、キャンセルの場合は reason: "cancelled" が返ります。
• エラー: invalid_count、invalid_view、invalid_lora_pass、invalid_subject_image、invalid_size、character_not_ready、および Multi-Ref のエラー（unknown_character、unknown_subject、unknown_lora、unknown_mention、multiref_too_many_references、invalid_strength...）。制限とエラーを参照してください。

ポーリング

GET /images/{jobId}

キューは共有されているため、3秒おきにポーリングしてください。それより頻繁なアクセスは避けてください。

ダウンロード

GET /images/{jobId}/file

レスポンスボディとしてPNG画像が返されます（Content-Type: image/png）。ステータスが completed になり次第ダウンロード可能ですが、レンダリングデータが削除されると 404 media_unavailable になります。すぐにダウンロードしてください。アーカイブは行われません。

キャンセル

POST /images/{jobId}/cancel

キュー待ちまたは実行中のレンダリングをキャンセルします。{ "ok": true } が返されます。料金は発生せず、キーの1日上限に対して確保されていたコストも返還されます。