Core concepts
リクエストとライフサイクル
生成は非同期です。受付後にジョブが作られ、バックグラウンドで処理が進みます。
リクエストのライフサイクル
| ジョブの状態 | 状態取得の status | 終端 | 意味 |
|---|---|---|---|
queued | IN_QUEUE | いいえ | 開始待ち。生成開始前は取り消せます。 |
processing | IN_PROGRESS | いいえ | 生成中。取り消せません。 |
completed | COMPLETED | はい | 成果物を取得できます。 |
failed | FAILED | はい | 失敗。ジョブの error を確認します。 |
canceled | CANCELED | はい | 生成開始前に取り消されました。 |
受付時の data.job.id を保存します。状態確認、結果取得、取消、Webhook の重複判定に使います。orchestor_status はジョブ本体と同じ小文字表記です。
重複した生成を防ぐ
生成時に 冪等性キーを送ると、受付結果が分からない通信切断でも同じ入力を安全に再送できます。
受付時の応答
主要フィールドを抜粋した例です。
{
"data": {
"job": {
"id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"status": "queued"
},
"status_url": "https://api.orchestor.io/v1/creative/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/status",
"result_url": "https://api.orchestor.io/v1/creative/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/result",
"cancel_url": "https://api.orchestor.io/v1/creative/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/cancel",
"terminal": false,
"result_ready": false,
"next_poll_after_seconds": 2
}
}返された URL を使い、next_poll_after_seconds 秒待ってから状態を確認します。terminal は処理の終了、result_ready は成果物の取得可否です。成功以外でも終端になります。
完了した成果物
result_ready が true になったら result_url を取得します。画像・動画・音声は、共通の data.result.artifacts に入ります。以下は結果の抜粋です。
{
"data": {
"status": "COMPLETED",
"result": {
"artifacts": [
{
"id": "artf_example",
"type": "image",
"url": "https://media.example.com/output.png",
"content_type": "image/png"
}
]
}
}
}モデルによっては model や file 型の成果物も返ります。checksum_sha256 があれば、ダウンロードしたファイルの SHA-256 と照合できます。
リクエストを取り消す
生成開始前のジョブだけ取り消せます。
curl --request POST "https://api.orchestor.io/v1/creative/jobs/$JOB_ID/cancel" \
--header "Authorization: Bearer $ORCHESTOR_API_KEY"成功すると 200 と data.canceled: true を返します。生成開始後は 409 job_generation_already_started、終端状態では 409 job_not_cancelable です。cancelable の確認後に状態が変わる場合もあるため、競合を処理してください。
成果物を保管する
長期保管が必要なファイルは自分のストレージへダウンロードしてください。保持の扱いは料金とデータ保持で確認します。