はじめに

画像生成

POST /v1/creative/image-router/generate は、モデル ID と入力を受け付けて画像生成ジョブを作成します。文章からの生成と画像編集を、モデルの対応入力に合わせて使い分けます。

モデルと入力を選ぶ

GET /v1/creative/image-router/models または GET /v1/creative/image-router/models/{model_id} で capabilities、constraints、pricing を確認します。例では公開カタログのモデル ID gpt-image-2 と nano-banana-pro を使用します。呼び出すワークスペースで利用可能な ID と入力の組み合わせを選んでください。

フィールド用途
model必須。カタログのモデル ID。
prompt必須。作りたい画像、または編集で変更したい内容。空文字列は使えません。
image_urls編集や参照に使う画像。1〜16件の公開 HTTPS URL。モデル固有の上限も適用されます。
mask_url編集領域を示すマスク。対応するモデルで指定します。
aspect_ratio縦横比。1:1、16:9 など。auto は入力画像に合わせます。
image_sizeプリセット、1024x1024、または { "width": 1024, "height": 1024 }。縦横比より優先されます。
quality・resolution品質と解像度。値はモデルごとの対応表で確認します。
num_images生成枚数。共通スキーマは1〜10ですが、モデルごとに上限があります。
output_formatpng、jpeg、jpg、webp、gif、svg のうち対応する形式。
background対応モデルの背景指定。auto、transparent、opaque。
rendering_speed対応モデルの速度と品質の配分。TURBO、BALANCED、QUALITY。
complexityGPT Image 2.6 系の描画前の計画量。low、medium、high。
frame_count・frame_duration_msGPT Image 2.6 系の GIF 出力のフレーム数と表示間隔。
model_paramsカタログで許可されたモデル固有の設定。不要なら省略または {}。
metadataジョブに関連付ける追跡用の値。モデルには送りません。

共通スキーマにある値でも、モデルが対応していない指定は 400 invalid_request になります。model_params に任意の提供元パラメータを追加せず、カタログの許可項目を確認してください。

文章から画像を作る

API キーはサーバーの環境変数に設定します。再試行で重複生成しないよう、同じ入力には同じ Idempotency-Key を使用します。

# 新しい生成を始めるときに一度だけ作り、再試行でも同じ値を使います。
export IDEMPOTENCY_KEY="$(uuidgen)"
curl -X POST https://api.orchestor.io/v1/creative/image-router/generate \
  -H "Authorization: Bearer $ORCHESTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "淡い灰色の背景に置かれた青いガラスの花瓶、正面からの自然光",
    "quality": "low",
    "aspect_ratio": "1:1",
    "mode": "async"
  }'

画像を編集する

画像編集に対応するモデルを選び、image_urls に元画像を指定します。ローカルファイルは先にアップロードしてください。INPUT_IMAGE_URL にはそのレスポンスの public_url を設定します。

// Node.js 24 以上のサーバー側で実行します。
const response = await fetch('https://api.orchestor.io/v1/creative/image-router/generate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORCHESTOR_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': process.env.IDEMPOTENCY_KEY,
  },
  body: JSON.stringify({
    model: 'nano-banana-pro',
    prompt: '花瓶の色だけを琥珀色に変更し、構図と背景は維持する',
    image_urls: [process.env.INPUT_IMAGE_URL],
    mode: 'async',
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { data } = await response.json();
console.log(data.job.id, data.status_url);

結果を受け取る

受付時の 200 OK は、data.job と状態・結果の URL を返します。status_url を next_poll_after_seconds ごとに取得し、result_ready が true になったら result_url を取得します。生成した画像は一枚ずつ result.artifacts に入ります。

通知で受け取る場合は mode: "webhook" と webhook_url を指定します。短時間だけ待つ場合は sync と wait_timeout_seconds を使い、時間内に終わらなければ同じジョブの状態確認へ移ります。

入力に問題があれば invalid_request、残高不足なら insufficient_funds、受付枠が埋まっていれば queue_full です。失敗後の再送は retryable と retry_after_seconds に従います。