はじめに

ジョブとポーリング

生成要求を送るとジョブが作成されます。応答の job.id を保存し、その ID で状態、成果物、イベント、取消を管理します。HTTP の成功は受付の成功です。生成が成功したかどうかはジョブの終端状態で判断します。

状態を読む

GET /v1/creative/jobs/{id}/status は二つの表記を返します。orchestor_status はジョブ本体の status と同じ小文字表記、レスポンス直下の status は大文字表記です。

ジョブの状態状態取得の status終端次の処理
queuedIN_QUEUEいいえキューで待機中。指定された間隔で状態を取得します。
processingIN_PROGRESSいいえ生成中。状態の取得を続けます。
completedCOMPLETEDはいresult_url から成果物を取得します。
failedFAILEDはいジョブの error とイベントを確認します。
canceledCANCELEDはい取消済み。結果はありません。

terminal: true は処理の終了、result_ready: true は成果物の取得可否を示します。成功以外でも終端になるため、この二つを区別してください。next_action は通常 poll_status、成功時は fetch_result、結果がない終端状態では inspect_events です。

応答方式を選ぶ

mode動作
async既定値。受付後に応答し、status_url で状態を確認します。
webhook終端状態を webhook_url に通知します。Webhookを参照してください。
syncwait_timeout_seconds の間、完了を待ちます。上限は30秒です。
subscribesync と同じ時間制限付きの待機です。継続的なイベントストリームではありません。

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 です。