API 参考/视频生成

视频生成 API

用 /v1/videos 提交异步视频任务，轮询状态后下载 MP4，按每秒单价 × 时长计费。

异步任务movie不想写代码？在浏览器里直接试试视频生成
本页内容expand_more

快速示例link

/v1/videos 是异步任务接口。平台在接受任务时预留费用并返回任务 ID；客户端需要轮询状态，完成后再下载 MP4 成片。

cURL
curl https://api.wokey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: video-demo-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jimeng-seedance-2.0-mini",
    "prompt": "A paper boat drifting through a neon-lit rainy street, cinematic tracking shot",
    "duration_seconds": 5,
    "ratio": "16:9",
    "video_resolution": "720p"
  }'

提交返回 202 和任务 ID；完成后通过 content_url 下载 MP4。

创建任务参数link

参数是否必填说明
model必填视频模型 ID，例如 jimeng-seedance-2.0-mini。可用模型、分辨率和时长组合以视频生成页的实时列表为准。
prompt必填视频提示词，不能为空。
duration_seconds必填视频时长（整数秒）。每个模型和价格 SKU 有各自的允许范围；也兼容 duration。
ratio必填画幅比例：1:1、3:4、4:3、9:16、16:9 或 21:9。
video_resolution必填输出分辨率，取值取决于模型，当前可能为 480p、720p、1080p 或 4k；也兼容 resolution。
mode可选默认 text_to_video。支持范围随模型变化，还可为 image_to_video、first_last_frames 或 multimodal_reference。带媒体输入时请使用 multipart/form-data。
image / first_frame / last_frame / video / audio条件必填仅用于带媒体的 mode，通过 multipart/form-data 上传。image_to_video 需 1 张 image；first_last_frames 各需 1 张首尾帧；multimodal_reference 支持最多 9 张图、3 个视频和 3 个音频。
Idempotency-Key建议放在请求 Header 中，长度 8-160 个安全字符。网络超时后使用同一 Key 重试，可避免重复创建和重复预留。

任务生命周期link

请不要长连接等待创建请求返回成片。推荐保存任务 ID，以适当间隔轮询，直到 status 变为 completed、failed 或 cancelled。

POST/v1/videos创建任务

返回 HTTP 202 和 object: "video"；status 初始为 in_progress。

GET/v1/videos/{id}查询状态

返回任务参数、状态、价格、错误信息和 content_url；上游排队时还会返回 queue.position、queue.length 与建议下次查询时间 next_poll_at。

GET/v1/videos/{id}/content下载成片

任务完成后返回 video/mp4。请尽快保存，平台不保证永久保留视频文件。

GET/v1/videos?limit=20列出任务

返回当前账号的视频任务，支持 limit 和 before 分页。

DELETE/v1/videos/{id}取消或删除

可取消尚在排队的任务，或删除已完成任务的成片；上游已开始生成后不能强制取消。

响应里的 price_usd 是本任务的预留/结算金额；完成后 content_url 指向需要同一 API Key 认证的成片下载路径。queue 为 null 表示当前没有经过校验的上游排位，并不代表任务失败。

计费说明link

视频按模型、分辨率和时长计费：总价 = 当前每秒单价 × duration_seconds。创建任务时预留这笔金额，生成成功后结算；失败或在提交前取消会释放预留。当前单价和可用 SKU 可在 API 接入页与视频生成页实时查看。

注意事项link

  • 视频任务可能需要数分钟；业务程序应持久化任务 ID，并对轮询使用退避。
  • 重试创建请求时请复用原 Idempotency-Key；同一 Key 不能用于不同参数。
  • 请及时下载成片；删除成片后 content_url 将不再可用。