异步任务

高耗时任务默认走异步：POST 创建任务返回 task_id，通过 GET /v1/generations/{task_id} 轮询或 callback_url 接收结果推送。

接口

GET /v1/generations/{task_id}
Authorization: Bearer sk-xxxxxxxx

该接口同时查询图片和视频生成任务。task_id 全局唯一,响应中的 kind 字段会标识任务类型。

路径参数

参数	类型	必填	说明
task_id	string	是	创建异步生成任务时返回的任务 ID

任务状态机

queued  →  running  →  succeeded
                   ↘   failed
                   ↘   refunded

status	含义
`queued`	在队列中,等待调度
`running`	执行中,有 `progress` 字段 (0–100)
`succeeded`	完成,有 `result` 字段
`failed`	失败,有 `error` 字段;已扣额度全额返还
`refunded`	已退款终态

查询任务

curl https://cokeapi.com/v1/generations/01HX... \
  -H "Authorization: Bearer sk-xxxxxxxx"

import httpx

r = httpx.get(
    "https://cokeapi.com/v1/generations/01HX...",
    headers={"Authorization": "Bearer sk-xxxxxxxx"},
    timeout=30,
)
print(r.json())

const r = await fetch("https://cokeapi.com/v1/generations/01HX...", {
  headers: { Authorization: `Bearer ${process.env.COKEAPI_KEY}` },
});

console.log(await r.json());

响应示例

进行中:

{
  "id": "01HX...",
  "task_id": "01HX...",
  "object": "video.generation.task",
  "status": "running",
  "progress": 35,
  "created": 1714200000,
  "model": "grok-video-3",
  "kind": "video",
  "mode": "t2v",
  "usage": {
    "total_cost": 400,
    "total_points": 4
  },
  "error": null
}

完成后:

{
  "id": "01HX...",
  "task_id": "01HX...",
  "object": "video.generation.task",
  "status": "succeeded",
  "progress": 100,
  "created": 1714200000,
  "model": "grok-video-3",
  "kind": "video",
  "mode": "t2v",
  "usage": {
    "total_cost": 400,
    "total_points": 4
  },
  "error": null,
  "result": {
    "id": "01HX...",
    "object": "video.generation",
    "created": 1714200000,
    "model": "grok-video-3",
    "data": [
      {
        "url": "https://cdn.cokeapi.com/v/01HX....mp4",
        "cover_url": "https://cdn.cokeapi.com/v/01HX....jpg",
        "duration_ms": 6000,
        "width": 1920,
        "height": 1080
      }
    ],
    "usage": {
      "total_cost": 400,
      "total_points": 4
    }
  }
}

失败:

{
  "id": "01HX...",
  "task_id": "01HX...",
  "object": "image.generation.task",
  "status": "failed",
  "progress": 5,
  "created": 1714200000,
  "model": "gpt-image-2",
  "kind": "image",
  "mode": "t2i",
  "usage": {
    "total_cost": 200,
    "total_points": 2
  },
  "error": {
    "message": "generation failed"
  }
}

错误码

HTTP	code	说明
401	`invalid_api_key`	API Key 缺失或无效
404	`not_found`	任务不存在,或任务不属于当前 API Key 对应用户
429	`rate_limit_exceeded`	请求过于频繁

Callback Webhook (推荐)

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

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

{
  "id": "01HX...",
  "status": "succeeded",
  "result": {
    "data": [
      {
        "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 秒轮询一次。
图片 / 视频任务从创建开始超过 15 分钟仍未进入终态时,系统会自动标记为 failed 并返还预扣额度。
不要用 < 1 秒间隔轮询,会快速消耗 RPM。

任务保留

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

错误处理

failed 任务的 error 字段包含失败信息:

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

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

本页目录