はじめに

クイックスタート

REST API を使って、受付から結果取得までの流れを確認します。

用意するもの

  • ワークスペースで利用できる API キーと生成用の残高
  • curl と jq
  • 利用可能なモデル ID(例では gpt-image-2)
API キーを保護する

API キーは残高を使用できる認証情報です。サーバー側で保管し、ソース管理に含めないでください。

1. 認証情報を設定する

export ORCHESTOR_API_KEY="YOUR_API_KEY"
export IDEMPOTENCY_KEY="$(uuidgen)"

2. 生成を送信する

RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST https://api.orchestor.io/v1/creative/image-router/generate \
  --header "Authorization: Bearer $ORCHESTOR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{"model":"gpt-image-2","prompt":"朝の光が差し込む木製テーブルの上の陶器","aspect_ratio":"1:1","mode":"async"}')
printf '%s' "$RESPONSE" | jq
JOB_ID=$(printf '%s' "$RESPONSE" | jq -er '.data.job.id')

受付時の応答から、ジョブ ID と状態確認先を保存します。以下は必要な項目の抜粋です。

{
  "data": {
    "job": { "id": "job_example", "status": "queued" },
    "status_url": "https://api.orchestor.io/v1/creative/jobs/job_example/status",
    "result_url": "https://api.orchestor.io/v1/creative/jobs/job_example/result"
  }
}

通信が切れ、受付結果が分からないときは同じ入力と冪等性キーで再試行してください。

3. 結果を確認する

STATUS=$(curl --silent --show-error --fail-with-body \
  "https://api.orchestor.io/v1/creative/jobs/$JOB_ID/status" \
  --header "Authorization: Bearer $ORCHESTOR_API_KEY")
printf '%s' "$STATUS" | jq '.data | {status, terminal, result_ready, next_poll_after_seconds}'

terminal が false なら、next_poll_after_seconds 秒待ってから再取得します。terminal が true でも、失敗・取消の場合は結果がありません。自動的な待機はポーリングを参照してください。

完了時の状態応答の抜粋です。

{
  "data": {
    "status": "COMPLETED",
    "orchestor_status": "completed",
    "terminal": true,
    "result_ready": true,
    "next_action": "fetch_result",
    "next_poll_after_seconds": null
  }
}

FAILED と CANCELED も終端状態です。成功時だけ、次の結果取得へ進みます。

result_ready が true のときに実行します。

RESULT=$(curl --silent --show-error --fail-with-body \
  "https://api.orchestor.io/v1/creative/jobs/$JOB_ID/result" \
  --header "Authorization: Bearer $ORCHESTOR_API_KEY")
printf '%s' "$RESULT" | jq '.data.result.artifacts'
IMAGE_URL=$(printf '%s' "$RESULT" | jq -er '.data.result.artifacts[0].url')
curl --fail --location "$IMAGE_URL" --output image.png

結果の data.result.artifacts には、次のように成果物が入ります(抜粋)。

{
  "data": {
    "result": {
      "artifacts": [{ "type": "image", "url": "https://example.com/generated-image.png", "content_type": "image/png" }]
    }
  }
}

次のステップ

関連ページ