非同期タスク

タスクの作成、状態照会、結果判定、課金ライフサイクル。

このページでは非同期のメディア生成タスクを説明します。作成時に残高を hold し、成功時に実使用量で settle、failed・expired では全額を解放します。履歴データの canceled も同様ですが、新しい受理済みタスクは取り消せません。

API

GET /api/v1/models?includeSchema=1&includeExamples=1
# choose an item where enabled && available

curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: render-001" \
  -d '{
    "model": "MODEL_ID_FROM_CATALOG",
    "input": { "prompt": "a folded paper lantern, hard side light" }
  }'

現在のキーのタスク履歴

GET /api/v1/jobs は、リクエストの認証に使った API キーのタスクだけを読み取ります。同じアカウントの別キーは指定できません。応答はメタデータのみで、input と output は含みません。選んだ taskId の結果は GET /api/v1/jobs/recordInfo で取得してください。

from と to は UTC の日付で、区間は [from, to) です。既定は 7 日間、最大 92 日間です。state と正確な model 参照で絞り込み、limit は既定 20、最大 100。hasMore が true なら nextCursor を次の cursor に渡し、from、to とほかの条件は固定してください。createdAt の降順、同時刻なら id の降順なので、同時刻のタスクも区別してページを進められます。各ページはその時点の状態を読むため、状態や絞り込み結果が固定されたスナップショットではありません。

四つの期限を区別する

deadlineAt はサーバーが返す実際のタスク期限です。SDK の timeoutMs はクライアントが待機する時間を制限するだけで、受理済みタスクを取り消しません。結果 URL の expiresAt は通常 20 分、生成メディアの保存期間は 14 日です。URL の失効はタスクの失敗やメディア削除を意味しません。

タスクを作成する

POST /api/v1/jobs/createTask に model、input、任意の callBackUrl を送ります。Idempotency-Key は論理リクエストごとに一つ発行し、ネットワーク再試行では同じ値を再利用してください。

状態を正しく判定する

新しいタスクでは queued と running が非終端、succeeded、failed、expired が終端です。過去の canceled は読み取り互換のために残る終端状態であり、現在の取消操作ではありません。HTTP 応答やレスポンス形式の code: 200 は照会成功のみを示し、生成結果は data.state で判定します。

output.assets[].pending が true の場合は保存処理中なので数秒後に再照会します。unavailable が true の場合は復旧できないため再生成が必要です。

通知とポーリング

本番では webhook を主経路にし、ポーリングは指数バックオフとジッターを付けた復旧経路にします。recordInfo と webhook は同じ {code,msg,data,request_id} レスポンス形式を返すため、一つのパーサーを共有できます。

完全なフィールド定義は OpenAPI 3.1 仕様を参照してください。