はじめに

制限と課金

リクエストの頻度と、ワークスペース内で受け付ける生成ジョブの数を分けて管理します。料金はモデルと入力条件で変わるため、生成前に見積もりと残高を確認します。

リクエストの頻度

レスポンスヘッダーで、現在の期間に使えるリクエスト数を確認します。

ヘッダー意味
ratelimit-limit現在の期間で許可されるリクエスト数。
ratelimit-remaining残りのリクエスト数。
ratelimit-reset制限がリセットされるまでの秒数。
retry-after再試行までの待機秒数。
x-orchestor-poll-after次のジョブ状態取得までの待機秒数。

429 が返った場合は送信頻度を下げ、待機時間を守ってください。ポーリングではレスポンスの next_poll_after_seconds を使い、短い間隔で呼び出し続けないようにします。上限値を固定せず、レスポンスに含まれる値を使用してください。

実行中・待機中のジョブ

generation_limits が返された場合は、次の値を使って送信量を調整します。このオブジェクトは null の場合もあります。

フィールド意味
concurrency_limit同時実行の上限。
queued_jobs_limit待機中ジョブの上限。
accepted_generation_jobs_limit受け付ける生成ジョブの上限。
active_generation_jobs実行中の生成ジョブ数。
queued_generation_jobs待機中の生成ジョブ数。
accepted_generation_jobs受け付け済みの生成ジョブ数。
queue_capacity_remainingキューに残っている容量。
wave_size_hint一度に送信する件数の目安。
limit_sourceプラン由来か、管理者による上書きか。

送信側の並列数を利用枠に合わせます。上限到達時はジョブの終了を待ち、再試行の指針に従ってください。

ジョブの料金

見積もり用の POST /v1/creative/estimate/{model} は、ジョブを作成せず、残高も消費しません。モデル ID と実際に生成する入力を渡します。

curl -X POST "https://api.orchestor.io/v1/creative/estimate/MODEL_ID" \
  -H "Authorization: Bearer $ORCHESTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "model": "MODEL_ID",
      "prompt": "朝の光が差し込む海辺",
      "aspect_ratio": "1:1"
    }
  }'

生成レスポンスの usage には credits が含まれ、usd や cost_details が付く場合があります。USD の見積もりとクレジット数は別の値として扱い、固定換算率をクライアント側に埋め込まないでください。

タイミング確認する内容
生成前モデル、画質・解像度・長さなどの入力、見積もり、利用可能残高。
送信後ジョブ ID と返された usage。
完了後ジョブの usage_summary と結果。
失敗・取消後ジョブの状態と課金情報。利用明細と照合します。

残高が足りない場合

API キーが属するワークスペースの残高は、GET /v1/creative/open/balance で確認します。

curl "https://api.orchestor.io/v1/creative/open/balance" \
  -H "Authorization: Bearer $ORCHESTOR_API_KEY"

data.balance には、利用可能クレジットの available_credits、残高状態の state、更新日時の updated_at、有効期限情報の expiration が含まれます。available_usd と請求枠の invoice は任意です。

402 が返った場合は error を読み、next_action が add_funds なら残高を確認してください。再送する前に、既存ジョブの状態と利用明細を確認します。

関連ページ