制限と課金
リクエストの頻度と、ワークスペース内で受け付ける生成ジョブの数を分けて管理します。料金はモデルと入力条件で変わるため、生成前に見積もりと残高を確認します。
リクエストの頻度
レスポンスヘッダーで、現在の期間に使えるリクエスト数を確認します。
| ヘッダー | 意味 |
|---|---|
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 なら残高を確認してください。再送する前に、既存ジョブの状態と利用明細を確認します。