统一视频生成 API

视频模型 API

使用 OpenAI 兼容的异步接口调用视频模型。任务创建后通过轮询接口获取最终视频地址。

POST /v1/videosGET /v1/videos/{task_id}Bearer Token

Auth

认证与地址

在 Tokencookie 控制台创建 API 密钥。请求必须使用 Authorization: Bearer 认证。

Base URL: https://www.tokencookie.com
Authorization: Bearer YOUR_TK_API_KEY
Content-Type: application/json

Models

模型列表

模型名必须使用下表中的 Tokencookie 模型名。模型分辨率固定，省略 resolution 时系统会自动补齐。

模型	固定分辨率
`sd-2.0-g1-480p`	`480p`
`sd-2.0-g1-720p`	`720p`
`sd-2.0-g1-1080p`	`1080p`
`sd-2.5-g1-480p`	`480p`
`sd-2.5-g1-720p`	`720p`
`sd-2.5-g1-1080p`	`1080p`

Fields

请求字段

字段	类型	必填	说明
`model`	string	是	使用模型列表中的名称。
`prompt`	string	是	视频生成提示词，不能为空。
`duration`	integer	否	整数 1-15 秒，默认 4 秒。
`seconds`	integer	否	`duration` 的兼容字段；同时存在时使用 `duration`。
`ratio`	string	否	默认 `16:9`；支持 `16:9`、`9:16`、`1:1`、`3:4`、`4:3`。
`aspect_ratio`	string	否	`ratio` 的兼容字段；优先使用 `ratio`。
`size`	string	否	如 `1920x1080`，仅在未传比例字段时推导比例。
`resolution`	string	否	必须与所选模型固定分辨率一致。
`first_image`	string	否	首帧图片公网 HTTP(S) URL。
`last_image`	string	否	尾帧图片公网 HTTP(S) URL。
`reference_images`	string[]	否	参考图片 URL 数组。
`reference_videos`	string[]	否	参考视频 URL 数组。
`reference_audios`	string[]	否	参考音频 URL 数组。

不要传入 mode。兼容层会根据参考素材自动决定模式；客户端传入 mode 会被拒绝。

Create

创建任务

文生视频

curl -X POST https://www.tokencookie.com/v1/videos -H "Authorization: Bearer YOUR_TK_API_KEY" -H "Content-Type: application/json" -d '{"model":"sd-2.0-g1-720p","prompt":"城市夜景中的霓虹灯倒映在雨后街道，镜头缓慢推进。","duration":5,"ratio":"16:9","resolution":"720p"}'

带参考素材

{
  "model": "sd-2.5-g1-1080p",
  "prompt": "保持人物外观一致，让人物从室内走向窗边。",
  "duration": 8,
  "ratio": "9:16",
  "first_image": "https://example.com/first.png",
  "reference_images": ["https://example.com/character.png"],
  "resolution": "1080p"
}

创建成功

{"id":"task_px_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","status":"queued"}

保存返回的 id，随后用于查询任务结果。

Result

查询与结果

curl https://www.tokencookie.com/v1/videos/TASK_ID -H "Authorization: Bearer YOUR_TK_API_KEY"

建议每隔 10-20 秒查询一次，直到状态为 completed 或 failed。

处理中

{"id":"TASK_ID","status":"processing","progress":48}

生成成功

{
  "id": "TASK_ID",
  "status": "completed",
  "progress": 100,
  "video_url": "https://tccdn.shenzhengyun.cn/video/2026/09/25/task_px_xxx.mp4",
  "result_url": "https://tccdn.shenzhengyun.cn/video/2026/09/25/task_px_xxx.mp4"
}

video_url 和 result_url 优先返回七牛 CDN 地址，客户端无需访问上游地址。

七牛上传失败时

{
  "id": "TASK_ID",
  "status": "completed",
  "progress": 100,
  "video_url": "https://proxy.tokencookie.com/trxdoc1/v1/videos/media/m_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "result_url": "https://proxy.tokencookie.com/trxdoc1/v1/videos/media/m_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

兼容层内部拉取上游视频，不会把上游真实 URL 返回给客户端。

Errors

错误处理

参数校验错误

{"error":{"message":"resolution must be 720p for sd-2.0-g1-720p","code":"invalid_request"}}

上游提交失败

{"detail":"余额不足或当前模型不可用"}

上游 JSON 错误会原样透传，具体字段以实际响应为准。

生成失败

{
  "id": "TASK_ID",
  "status": "failed",
  "progress": 0,
  "error": {"message":"上游返回的具体失败原因","code":"上游错误码"}
}

生成失败时会保留上游错误信息；七牛上传失败信息由服务端日志记录，客户端不会看到上游视频地址。