异步任务

视频生成与高质量图片任务为异步模型,本页统一说明任务状态、轮询与回调。

视频生成、quality=hd 的图像生成任务通常 > 5 秒,CokeAPI 默认走异步:POST 创建任务立刻返回 task_id,之后通过 GET /v1/{kind}/generations/{task_id} 轮询,或在创建时传 callback_url 让平台主动 POST 推送。

任务状态机

queued  →  running  →  completed
                   ↘   failed
                   ↘   cancelled

status	含义
`queued`	在队列中,等待调度
`running`	执行中,有 `progress` 字段 (0–100)
`completed`	完成,有结果字段 (`url` / `video_url` 等)
`failed`	失败,有 `error` 字段;已扣点数全额返还
`cancelled`	客户端主动取消;已完成的不退款

查询任务

通用规律:GET <创建任务的 URL>/{task_id}。

# 视频
curl https://api.cokeapi.com/v1/video/generations/video_01HX... \
  -H "Authorization: Bearer sk-coke-xxxxxxxx"

# 图像 (异步分支)
curl https://api.cokeapi.com/v1/images/generations/img_01HX... \
  -H "Authorization: Bearer sk-coke-xxxxxxxx"

取消任务

curl -X DELETE https://api.cokeapi.com/v1/video/generations/video_01HX... \
  -H "Authorization: Bearer sk-coke-xxxxxxxx"

仅 queued / running 任务可取消;completed 已结算,不退点。

Callback Webhook (推荐)

创建任务时传 callback_url,任务进入终态 (completed / failed) 时,CokeAPI 会向该 URL 发起一次 POST:

POST https://your.app/webhooks/cokeapi
Content-Type: application/json
X-Coke-Signature: sha256=<HMAC>

{
  "id": "video_01HX...",
  "status": "completed",
  "video_url": "https://cdn.cokeapi.com/v/01HX....mp4",
  ...
}

Webhook 要点

5 秒内必须返回 2xx,否则平台会重试 (最多 3 次,指数退避 5s/30s/2m)。
校验签名:X-Coke-Signature 头是 sha256(secret + body),secret 在控制台「回调」页生成。
回调可能重复:用 id 字段做幂等,同一任务多次回调不要副作用累加。

轮询建议

视频任务 p95 ~70 秒,5 秒轮询一次足够。
图像异步任务 p95 ~15 秒,2 秒轮询一次。
不要用 < 1 秒间隔轮询,会快速消耗 RPM。

任务保留

completed 任务 (含结果 URL) 保留 24 小时,过期 URL 失效。
failed / cancelled 任务详情保留 7 天,便于排障。

错误处理

failed 任务的 error 字段:

{
  "id": "video_01HX...",
  "status": "failed",
  "error": {
    "type": "upstream_unavailable",
    "code": 502201,
    "message": "GROK 服务暂不可用,已自动切换账号池仍失败",
    "trace_id": "01HX..."
  },
  "created": 1714200000,
  "completed": 1714200030
}

错误码与同步接口一致,见错误码。

On this page