视频生成

视频生成是异步流程：提交一次，保存任务 ID，轮询至完成，再下载文件。在 Seedance、grok-imagine-video-1.5 和 kling-video-v3 之间选定型号，不要把不同型号的参数直接混用。

1. 创建 Seedance 任务

curl --fail-with-body https://enterprise.beefapi.com/v1/videos \
  -H "Authorization: Bearer $BEEFAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-mini","prompt":"一只橘猫趴在窗台，微风吹动窗帘，镜头缓慢推近","seconds":"5","metadata":{"resolution":"720p","ratio":"16:9"}}' \
  -o video-task.json

示例响应（仅展示关键字段）：

{"id":"task_example","object":"video","model":"seedance-2.0-mini","status":"queued"}

将实际返回的 id 保存到数据库或任务队列中。HTTP 成功表示任务已受理，不代表视频生成完成。

export VIDEO_ID="$(python3 -c 'import json; print(json.load(open("video-task.json"))["id"])')"

2. 查询同一个任务

curl --fail-with-body "https://enterprise.beefapi.com/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $BEEFAPI_KEY"

`status`	下一步
`queued`	排队中，继续等候
`in_progress`	生成中，继续轮询
`completed`	开始下载
`failed`	停止轮询，保留 `error` 和任务 ID
`expired`	上游或本站的结果保存期已过；保留任务 ID 与账单，不要据此重新生成
`unknown` 或未识别值	保留响应并核查，不要当作成功或自动重新生成

任务列表与取消/删除见 Seedance 参数与素材的「列表与删除」一节。

建议每 5 秒查询一次，遇到限流降低频率。设置轮询次数或总时间上限；达到上限只表示客户端停止等待，任务可能仍在执行，之后应继续查询原 ID。

3. 下载并保存

curl --fail --location \
  "https://enterprise.beefapi.com/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $BEEFAPI_KEY" \
  -o video.mp4

接口可能重定向至临时地址。不要使用 --location-trusted，避免把 Key 转发至文件托管域名。临时地址不能用作永久素材链接；完成后将文件存入自己的存储，并验证能够播放。

下载遇到 video_delivery_pending 时，按 Retry-After 等待后重新下载原任务。不要再次创建视频。某些结果地址过期后无法恢复；重新获取下载地址也不等于恢复已经不存在的文件。详见下载接口。

上游按自己的规则拒绝参考素材时返回 video_provider_constraint，message 按站点语言给出并引用本站为该型号配置的上限。提交前先按 Seedance 能力表自查参考素材的数量与合计时长，不要靠反复重提试探。

Grok 文生视频

同样请求 POST /v1/videos，JSON 如下：

{
  "model": "grok-imagine-video-1.5",
  "prompt": "A paper boat drifts across a puddle, cinematic close-up",
  "duration": 4,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "generate_audio": false
}

参数	Grok 支持范围
`duration`	1–15 秒，默认 4；参考模式最多 10 秒
`resolution`	`480p`、`720p`、`1080p`，默认 `480p`；参考模式限 `720p`
`aspect_ratio`	`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`，默认 `16:9`
`image`	首帧，URL 字符串或 `{ "url": "..." }`
`reference_images`	最多 7 张，使用 URL 对象数组；不与 `image` 同时发送
`generate_audio`	布尔值；`false` 请求无声，省略使用模型默认

单图示例：

{"model":"grok-imagine-video-1.5","prompt":"镜头缓慢推近，树叶随风摇动","image":{"url":"https://example.com/first-frame.png"},"duration":6,"aspect_ratio":"9:16","resolution":"720p"}

将素材 URL 换为自己的公开可访问 HTTPS 地址。Grok 参考模式用 reference_images，Seedance 用带角色的 content。Grok 当前型号不提供视频编辑、延长或 remix；不要通过改旧型号名称绕过能力限制。

可灵 Kling

同样请求 POST /v1/videos，参数是扁平的：

{
  "model": "kling-video-v3",
  "prompt": "一只橙色小猫坐在窗台看向镜头，阳光洒落",
  "duration": 3,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}

参数	Kling 支持范围
`duration`	3–15 秒的整数，默认 5
`resolution`	当前企业报价只开放 `720p`；其他分辨率会因没有对应价格被拒绝
`aspect_ratio`	`16:9`、`9:16`、`1:1`，默认 `16:9`；图生视频不传此参数
`image`	首帧图片地址，字符串或 `{ "url": "..." }`，一次只能给一张
`content`	也可改用带 `first_frame` 角色的素材数组表达首帧

图生视频示例：

{"model":"kling-video-v3","prompt":"让这只猫的尾巴轻轻摆动","duration":3,"resolution":"720p","image":"https://your-cdn.example.com/cat.png"}

首帧地址必须是上游能够访问到的公网图片。上游取不到图片时会直接判定任务失败，错误形如 Please input the ImageURL that can be retrieved from the external network.；换成可公开访问的地址后重新提交即可，这类失败任务不会按成功计费。

Kling 的结果与 Seedance 一样通过 GET /v1/videos/{task_id} 查询、GET /v1/videos/{task_id}/content 下载，下载得到 video/mp4。

费用与重试

Seedance 按实际视频 token 结算；Grok 按所选分辨率的秒价，并按报价计算参考图片费用；可灵按输出秒数 × 分辨率秒价结算，首帧图片不计入计费。企业实时人民币报价在模型与价格。

提交会预留额度，最终费用可能与预扣不同。网络断开、轮询超时或下载失败不能直接证明已退款。读取用量记录中的结算状态；不要用反复提交来查询进度。