视频任务管理

宁享Token 提供统一的视频任务管理接口，可用于查询任务状态、获取任务结果、删除任务、以及通过内容代理访问生成的视频文件。

统一任务端点

所有视频生成任务（包括 Seedance、Kling、欢乐马 happyhorse 系列）的 OpenAI 兼容端点共用同一套任务管理接口：

端点	方法	说明
/v1/video/generations	POST	提交任务（所有模型）
/v1/video/generations/{task_id}	GET	查询任务状态
/v1/video/generations/{task_id}	DELETE	删除任务
/v1/video/generations/{task_id}/content	GET	内容代理（转发视频文件流）

查询任务

GET/v1/video/generations/{task_id}

查询视频生成任务的状态与结果。

Bearer Token

请求示例

curl "/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

TASK_ID = "task-abc123"
r = requests.get(
    f"/v1/video/generations/{TASK_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
).json()
if r["status"] == "completed":
    print(r["metadata"]["url"])

响应示例

查询响应

{
  "id": "task-abc123",
  "object": "video",
  "model": "kling-3.0",
  "status": "completed",
  "created_at": 1735662000,
  "completed_at": 1735662120,
  "metadata": {
    "url": "https://.../abc.mp4?X-Tos-Expires=86400&..."
  }
}

任务状态

status	含义
queued	排队中
in_progress	生成中
completed	生成成功
failed	生成失败
cancelled	已取消（排队中删除，预扣费已退）

删除任务

DELETE/v1/video/generations/{task_id}

删除已完成/已失败的任务记录；运行中任务不可取消。

Bearer Token

对齐火山方舟语义：删除已完成或已失败的任务记录。运行中的任务无法取消（返回 409），需等待其进入终态后再删除。

请求示例

r = requests.delete(
    f"/v1/video/generations/{task_id}",
    headers={"Authorization": "Bearer <YOUR_API_KEY>"},
)
print(r.json())  # {"id": "...", "object": "video.deleted", "deleted": true}

响应说明

场景	HTTP	响应
已完成/已失败任务	200	{"id": "...", "object": "video.deleted", "deleted": true}，记录已删除
运行中任务	409	{"deleted": false, ...}，任务继续运行，无法取消
任务不存在	404	{"error": {"message": "task not found"}}

删除任务不影响已结算的计费。任务失败是否计费按上游厂商官方返回的计费信息核算，详见错误码 · 任务失败会扣费吗。

内容代理

GET/v1/video/generations/{task_id}/content

通过 宁享Token 代理访问生成的视频文件，支持 Range 请求用于流式播放。

Bearer Token

请求示例

# 直接下载
curl "/v1/video/generations/$TASK_ID/content" \
  -H "Authorization: Bearer $TOKEN" \
  -o video.mp4

# 流式播放（Range 请求）
curl "/v1/video/generations/$TASK_ID/content" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Range: bytes=0-1048575" \
  -o chunk.bin

HTML5 视频播放示例

<video controls>
  <source src="/v1/video/generations/TASK_ID/content" type="video/mp4">
</video>

注意：HTML5 标签直接使用时需在 URL 上附加 token，或通过后端代理添加 Authorization 头。

任务列表

GET/v1/video/generations

分页查询当前 API Key 的视频任务列表。

Bearer Token

请求参数

对齐火山方舟「查询视频生成任务列表」规范：

任务列表查询参数

参数	类型	必填	默认值	描述
page_num	integer	否	1	页码
page_size	integer	否	20	每页数量，最大 100
filter.status	string	否	-	按状态过滤：queued / in_progress / completed / failed
filter.model	string	否	-	按模型过滤（模型 ID）

响应示例

对齐火山列表规范，顶层仅 total + items 两个字段：

列表响应

{
  "total": 42,
  "items": [
    { "id": "cgt-1", "object": "video", "model": "kling-3.0", "status": "completed", "created_at": 1735662000 },
    { "id": "cgt-2", "object": "video", "model": "doubao-seedance-2-0", "status": "in_progress", "created_at": 1735662100, "progress": 50 }
  ]
}

列表项结构与单任务查询响应一致（object=video、OpenAI 状态枚举）。仅返回当前 API Key 名下的任务。

注意事项

• 任务记录：仅保留最近 7 天（对齐火山方舟），过期后自动清除，请及时保存结果。
• 视频 URL 有效期 24 小时：视频 URL 为对象存储签名链接（X-Tos-Expires=86400），每次查询重新签名生成新 URL。请及时下载或转存，不要当作长期固定地址。
• 任务取消限制：运行中的任务无法取消（DELETE 返回 409）；仅已完成/已失败的任务可删除记录。排队中的任务删除会尝试取消并退款。
• 内容代理支持 HTTP Range 请求，可用于 HTML5 video 标签的流式播放。
• 内容代理的鉴权使用 Authorization 头；URL 不可直接暴露给前端，需通过后端代理转发。
• 任务失败是否收费按上游厂商官方返回的计费信息核算（官方明确不计费才退还预扣；官方已计费的维持计费），详见错误码 · 任务失败会扣费吗；成功后删除任务不退费。