Genace 文档Jobs
查询、订阅与取消生成任务
每个生成请求（视频 / 图片）都会返回一个
job_id。使用下面的端点获取结果。
GET /v1/jobs/:id
单次查询，或长轮询直至任务到达终态（succeeded / failed / canceled）。
GET /api/v1/jobs/:id?wait=60
Authorization: Bearer sk_xxx查询参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
wait | number (0-60) | 0 | 长轮询秒数。0 立即返回当前状态；1..60 会每 2s 轮询一次上游，直至到达终态或超时。 |
响应 200
{
"id": "abc123",
"state": "succeeded",
"progress": 100,
"model": "seedance-2.0-fast",
"modality": "video",
"outputs": [
{ "url": "https://...", "type": "video", "meta": {} }
],
"error": null,
"created_at": "2026-05-29T10:00:00Z",
"started_at": "2026-05-29T10:00:02Z",
"finished_at": "2026-05-29T10:00:18Z",
"credits_held": 25,
"credits_actual": 25
}state 取值为 queued / running / succeeded / failed / canceled 之一。
在任务到达终态之前，outputs 和 error 均为 null。
错误
| 状态码 | type | 说明 |
|---|---|---|
| 404 | not_found | 任务不存在 |
| 403 | forbidden | 任务属于其他用户 |
GET /v1/jobs/:id/stream
SSE 进度流 —— Playground 和 SDK 客户端用它在不轮询的情况下渲染进度条。
GET /api/v1/jobs/:id/stream
Authorization: Bearer sk_xxx事件
| 事件 | 触发时机 | Payload |
|---|---|---|
progress | 非终态期间每约 2s 一次 | { state, progress, outputs: null, error: null } |
done | 任务到达 succeeded | { state, progress, outputs, error: null } |
error | 任务到达 failed / canceled | { state, progress, outputs: null, error } |
流会在 done 或 error 之后自动关闭。Vercel 函数执行时长上限为 60s ——
如果视频任务耗时更长，客户端应重新连接以恢复流。
示例
curl -N "https://genace.ai/api/v1/jobs/abc123/stream" \
-H "authorization: Bearer sk_xxx"POST /v1/jobs/:id/cancel
取消任务：将 state 设为 canceled，并退还预扣的 credits。
POST /api/v1/jobs/:id/cancel
Authorization: Bearer sk_xxx上游 Provider 并不会真正收到停止通知（这是 MVP 阶段的权衡 —— 在上游侧 取消一个短视频任务的复杂度并不值得投入，因此任何在途的上游结果到达后会 被直接丢弃）。
响应 200
{
"id": "abc123",
"state": "canceled",
"canceled_at": "2026-05-29T10:00:05Z"
}取消一个已处于终态的任务是幂等的 —— 会返回 200，任务的现有 state
保持不变。
错误
| 状态码 | type | 说明 |
|---|---|---|
| 404 | not_found | 任务不存在 |
| 403 | forbidden | 任务属于其他用户 |