画像生成
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_format | png、jpeg、jpg、webp、gif、svg のうち対応する形式。 |
background | 対応モデルの背景指定。auto、transparent、opaque。 |
rendering_speed | 対応モデルの速度と品質の配分。TURBO、BALANCED、QUALITY。 |
complexity | GPT Image 2.6 系の描画前の計画量。low、medium、high。 |
frame_count・frame_duration_ms | GPT 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 に従います。