ジョブとポーリング
生成要求を送るとジョブが作成されます。応答の job.id を保存し、その ID で状態、成果物、イベント、取消を管理します。HTTP の成功は受付の成功です。生成が成功したかどうかはジョブの終端状態で判断します。
状態を読む
GET /v1/creative/jobs/{id}/status は二つの表記を返します。orchestor_status はジョブ本体の status と同じ小文字表記、レスポンス直下の status は大文字表記です。
| ジョブの状態 | 状態取得の status | 終端 | 次の処理 |
|---|---|---|---|
queued | IN_QUEUE | いいえ | キューで待機中。指定された間隔で状態を取得します。 |
processing | IN_PROGRESS | いいえ | 生成中。状態の取得を続けます。 |
completed | COMPLETED | はい | result_url から成果物を取得します。 |
failed | FAILED | はい | ジョブの error とイベントを確認します。 |
canceled | CANCELED | はい | 取消済み。結果はありません。 |
terminal: true は処理の終了、result_ready: true は成果物の取得可否を示します。成功以外でも終端になるため、この二つを区別してください。next_action は通常 poll_status、成功時は fetch_result、結果がない終端状態では inspect_events です。
応答方式を選ぶ
mode | 動作 |
|---|---|
async | 既定値。受付後に応答し、status_url で状態を確認します。 |
webhook | 終端状態を webhook_url に通知します。Webhookを参照してください。 |
sync | wait_timeout_seconds の間、完了を待ちます。上限は30秒です。 |
subscribe | sync と同じ時間制限付きの待機です。継続的なイベントストリームではありません。 |
sync.timed_out または sync.capacity_exhausted が true でも、ジョブは継続します。返された ID と status_url を保存し、ポーリングへ切り替えます。
状態を取得する
curl "https://api.orchestor.io/v1/creative/jobs/$JOB_ID/status" \
-H "Authorization: Bearer $ORCHESTOR_API_KEY"次の取得までは next_poll_after_seconds 秒待ちます。HTTP ヘッダーの x-orchestor-poll-after も同じ目的で使用できます。キューが延期されている場合は queue.available_at と queue.retry_after_seconds も確認します。
Node.js 24 以上での例です。呼び出し元の待機時間には上限を設け、期限を過ぎたらジョブ ID を保存して後で確認します。
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
async function waitForJob(jobId, apiKey, timeoutMs = 600_000) {
const url = `https://api.orchestor.io/v1/creative/jobs/${encodeURIComponent(jobId)}/status`;
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
const response = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
signal: AbortSignal.timeout(Math.min(30_000, deadline - Date.now())),
});
const body = await response.json();
if (!response.ok) {
if (!body.error?.retryable) throw new Error(body.error?.message ?? `HTTP ${response.status}`);
const seconds = Number(response.headers.get('retry-after') ?? body.error.retry_after_seconds ?? 5);
await sleep(Math.min(seconds * 1000, Math.max(0, deadline - Date.now())));
continue;
}
if (body.data.terminal) return body.data;
const seconds = body.data.next_poll_after_seconds ?? 2;
await sleep(Math.min(seconds * 1000, Math.max(0, deadline - Date.now())));
}
throw new Error(`待機時間を超えました。ジョブ ${jobId} を後で確認してください。`);
}自分のプログラムが待機をやめても、ジョブは取り消されません。同じ生成を新しいキーで送り直すと別ジョブになるため、元の ID で確認を再開します。通信障害で受付結果が分からないときは、同じ入力と Idempotency-Key で再送します。
結果とイベントを取得する
curl "https://api.orchestor.io/v1/creative/jobs/$JOB_ID/result" \
-H "Authorization: Bearer $ORCHESTOR_API_KEY"成功時は data.result.artifacts にファイルの URL、MIME タイプ、サイズなどが入ります。checksum_sha256 がある場合はダウンロード後の SHA-256 と比較できます。
409 のコード | 意味と対処 |
|---|---|
job_not_completed | 待機中か生成中です。状態確認に戻ります。 |
job_failed | 失敗したジョブです。入力とジョブのエラーを確認します。 |
job_canceled | 取り消されたジョブです。成果物は取得できません。 |
GET /v1/creative/jobs/{id}/events は job.created、job.queued、job.started、generation.submitted、終端イベント、webhook.delivery を返します。生成の進行と通知の配信を分けて調べるときに使います。
一覧と取消
GET /v1/creative/jobs?limit=20&status=completed で新しい順に取得します。limit は1〜100件、type と status で絞り込み、次のページには next_cursor を starting_after として渡します。GET /v1/creative/jobs/{id} は入力の input や精算の usage_summary を含むジョブ全体を返します。
curl -X POST "https://api.orchestor.io/v1/creative/jobs/$JOB_ID/cancel" \
-H "Authorization: Bearer $ORCHESTOR_API_KEY"取消は生成開始前だけ可能です。状態の cancelable と cancel_url を確認します。確認後に生成が始まる場合もあるため、409 job_generation_already_started を処理してください。終端状態のジョブは 409 job_not_cancelable です。