genkiln

查询任务

GET /v1/tasks/{id}：读取任务的状态、输出地址和错误信息。包含任务对象与状态说明。

HTTP
GET https://genkiln.com/v1/tasks/{id}

返回你账号下的一个任务。其他账号的任务返回 404 not_found。

curl https://genkiln.com/v1/tasks/task_01JC8ZQ0E6H2P4N7K9T3W5Y8VA \
  -H "Authorization: Bearer $GENKILN_API_KEY"

任务对象

JSON
{
  "id": "task_01JC8ZQ0E6H2P4N7K9T3W5Y8VA",
  "object": "task",
  "model": "veo-3.1-fast",
  "status": "succeeded",
  "cost_credits": 390,
  "refunded": false,
  "output": {
    "images": [],
    "videos": [
      { "url": "https://cdn.genkiln.com/results/.../0.mp4", "duration": 8 }
    ]
  },
  "error": null,
  "created_at": "2026-11-03T08:00:00.000Z",
  "started_at": "2026-11-03T08:00:09.000Z",
  "completed_at": "2026-11-03T08:01:12.000Z",
  "expires_at": "2026-12-03T08:01:12.000Z",
  "metadata": { "order_id": "abc123" }
}
字段类型说明
idstring任务 ID，task_ 加 26 个字符，按创建时间有序。
objectstring固定为 task。
modelstring请求的模型 ID。
statusstringqueued、processing、succeeded、failed 或 canceled，见下文。
cost_creditsinteger创建任务时扣除的积分。
refundedboolean积分已退回余额时为 true（失败或取消的任务）。
outputobject | null仅在 succeeded 时有值：images 与 videos 数组，元素为 { url }。模型支持时长参数时，视频还带 duration（秒）。
errorobject | null任务失败或取消时为 { code, message }，否则为 null。
created_atstringISO 8601 时间（UTC）。
started_atstring | null开始生成的时间。
completed_atstring | null进入最终状态的时间。
expires_atstring | null成功任务的输出文件删除时间，即 completed_at 后 30 天。
metadataobject你传入的 metadata，未传则为 {}。

状态

状态最终含义
queued否已受理，等待开始。
processing否生成中，或正在保存结果文件。
succeeded是完成，output 中是结果地址。
failed是未完成，error 说明原因；积分已退还（refunded: true）。
canceled是被我们取消，例如模型下架。积分已退还。

最终状态不会再改变。结果文件保存完成前任务保持 processing，所以看到 succeeded 时 output 中的地址一定可用。

任务错误码

`error.code`含义
generation_failed生成失败。
content_rejected提示词或输入素材被内容安全策略拒绝。
invalid_input输入无法处理，例如图片 URL 无法下载。
timeout任务未在时限内完成（图像 15 分钟，视频 45 分钟，从 created_at 起算）。
service_busy服务暂时繁忙，请稍后重试。
canceled任务被取消。

无论哪种错误码，失败或取消的任务都会退款。

输出文件

  • 结果地址位于 https://cdn.genkiln.com，无需鉴权即可下载。拿到地址的人都能访问，地址本身不可猜测。
  • 文件在任务完成后保存 30 天（expires_at），之后删除。需要的文件请复制到你自己的存储。
  • 格式：图像为 PNG、JPEG 或 WebP；视频为 MP4 或 WebM。

轮询建议

图像任务每 3–10 秒、视频任务每 10–30 秒轮询一次，到最终状态即停止。查询会计入限流。任务量大时，Webhook 比轮询更省。