DEVELOPER GUIDE / V0.6

从提示词，到视频链接。

使用分配给你的客户 Key，上传图片并提交异步任务。生成完成后获取上游视频链接，视频文件不经过中转服务器下载。

内部测试版：地址以服务方提供为准。先调用 GET /healthz 查看 generation_enabled；为 false 时上传可用，生成返回 503。不要将本机测试地址交给客户当作已上线地址。

1. 地址与授权

当前云端接口根地址：

export BASE_URL="https://api.ganggangai.de"

本文中的 BASE_URL 是接口根地址（不含 /v1）。除健康检查外，每次请求都要带：

Authorization: Bearer YOUR_API_KEY

客户 Key 无权进入管理后台。同一客户的多个 Key 共享图片、任务和调用限制；不同客户的数据互相隔离。Key 可以重复调用，不是一次性令牌；管理员可在后台查看和复制新建 Key。Key 撤销后立即失效。

2. 上传参考图片（可选）

curl "$BASE_URL/v1/images" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @reference.png

请求体直接放图片文件，不使用 multipart 或 Base64。支持 PNG、JPEG、静态 WebP；单张最多 10 MiB、2400 万像素、最长边 12000。返回 {"id":"图片 UUID","width":1024,"height":1024,"bytes":12345}（示例数值）。每客户累计图片存储上限 1 GiB；闲置或完成任务的图片保留48小时，未完成任务引用的图片保留，详见下方保留规则。

3. 提交视频任务

curl "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: request-your-unique-id" \
  -d '{"prompt":"描述你希望生成的视频","image_ids":[],"ratio":"9:16","seconds":15,"useFast":true}'

字段	说明
`prompt`	必填，1–20000 个字符，不能全为空白。
`image_ids`	可选，最多 9 个本客户上传得到的图片 ID，不可重复。每张图片单独上传，再按数组顺序组成参考图1、参考图2……；顺序会参与重复提交检查。
`ratio`	9:16（默认）、16:9、1:1、4:3、3:4、21:9。
`seconds`	视频时长，4–15 的整数秒数，例如 15。推荐明确传入；测试页默认 10 秒。省略时沿用旧行为，不指定时长。
`force15s`	旧版兼容参数，推荐使用 seconds。true 表示 15 秒；同时传 seconds 时只允许 15，否则返回 400 duration_conflict。
`useFast`	布尔值，默认 true，沿用原工作台的生成偏好。

发送文字示例

若传入两张参考图、ratio 为 9:16、seconds 为 15、useFast 为 true，实际拼接如下。客户只需传用户提示词，不用重复固定模板：

帮我生成视频：比例 「9:16」【参考图对应关系】
参考图1：素材名 "参考图1"
参考图2：素材名 "参考图2"
用fast，15s视频
【用户提示词】
描述你希望生成的视频

useFast 为 false 时对应一行是 15s视频，不包含“用fast”。时长同时写入首次上游请求参数；它是请求值，最终生成是否符合时长仍以实际结果为准。接口测试页提供同样的文字预览，支持最多 9 张图片、调整顺序与移除。

成功返回 HTTP 202 和 {"id":"任务 UUID","status":"queued"}。这代表已受理，不代表视频已经生成。

重复请求：提交标识为 8–100 位字母、数字、下划线或短横线。同一客户、同一标识和相同内容返回原任务；改变内容会返回 409。请求超时后应保留原标识重试，不能换新标识盲目提交。

4. 查询任务

curl "$BASE_URL/v1/videos/TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

建议每 10–20 秒查询一次。任务完成状态为 complete，查询和 /result 使用同一下载结果，复用已确认的无水印设置。若链接暂未就绪，仍返回 complete，同时 video_url:null 和 result_error；继续查询原任务即可，不能因此重新生成。

状态	客户端行为
queued / preparing / uploading / submitting / confirming / rescuing / running	继续等待和查询。
awaiting_confirmation / rescue_waiting	等待服务方处理，不重复创建任务。
complete	获取视频链接。
failed / cancelled / legacy	停止轮询，核对结果或联系服务方。
paused / unknown	需要管理员核对；unknown 不等于失败，不能自动重发。

调度和状态说明

响应新增 status_label（中文展示状态）、attempt_count（账号尝试次数）。失败时 error.code 和 error.category 区分凭据不可用、配额不足、服务异常与内容受限；具体说明在 error.message。程序逻辑仍按 status 判断，展示使用 status_label。

管理员可选择故障转移或轮询。明确未受理的提交失败会换其他可用账号；同一任务每个账号最多尝试一次，任务编号和客户受理计数不变。账号额度沿用北京时间每日8点本地规则，等待时预留，明确失败释放，成功视频结算。结果未知不换号重发；应查询原任务或联系管理员。

5. 获取或刷新视频链接

curl "$BASE_URL/v1/videos/TASK_ID/result" \
  -H "Authorization: Bearer $API_KEY"

返回 {"id":"任务 UUID","video_url":"https://上游地址/…"}。这是 JSON 接口，不返回视频二进制。链接可能过期，可重新请求刷新；刷新仍失败时联系服务方。

下载上游视频时不要携带你的 API Key。本接口不保证永久保存视频，是否可匿名访问及有效期需以真实任务验收为准。

运行和保留规则

暂停及待核对任务不占全局或客户待处理数，也不占本地生成槽位；结果未知时仍保留额度，因为豆包可能继续生成。新证据确认未生成且可安全重试后，会更新原尝试并换号，任务编号不变。默认同时提交2个、生成4个、单账号生成1个、查询上游4个；管理员可调整。账号连续3次服务／登录异常或未知提交结果会暂停分配，须检查并恢复；额度不足和内容限制不计入连续服务异常。

图片全局上限10 GiB、每客户1 GiB。闲置满48小时自动清理，每10分钟检查；未完成任务引用的图片保留，任务完成后再保留48小时。过期图片ID返回404，需要重新上传。磁盘使用达到85%或剩余不足1 GiB会告警；达到95%或剩余不足256 MiB停止新图片上传。

GET /healthz 表示进程在线；GET /readyz 会综合启动恢复、健康账号、至少2点剩余额度、磁盘可写性和调度心跳返回200或503。监控不会发送收费探测视频，可受理不保证上游生成成功。后台“运行概览”显示磁盘和服务状态，“豆包账号”显示逐账号提交／成功／失败／连续异常及恢复入口。

限制与错误

每个客户的每分钟请求数、每日受理数、待处理数由管理员设置。每日受理数按北京时间计算，已失败任务仍算当日受理；它是防滥用限制，不是收费余额。相同标识重试不会重复计数。

{"error":{"code":"generation_disabled_for_testing"}}

400 invalid_seconds / duration_conflict	时长不是 4–15 的整数，或与旧版 15 秒参数冲突。
401 invalid_api_key	Key 无效、被撤销或客户已停用。
404 image_not_found / task_not_found	记录不存在或不属于当前客户。
409 idempotency_conflict / video_not_ready	提交标识与内容冲突，或视频尚未完成。
429 rate_limit / daily_task_limit / client_queue_full / queue_full	请求、当日受理或队列上限。
503 generation_disabled_for_testing	内部测试锁定，不会建立生成任务。
503 storage_unavailable / upstream_accounts_abnormal	存储或号池异常，需管理员处理。
413 global_image_storage_limit	全局图片存储超过10 GiB。
503 upstream_account_unavailable	凭据不可用：没有已登录、已启用的账号。
429 upstream_quota_unavailable	可用账号的每日预算不足，或上游已提示今日额度耗尽。
503 scheduler_cooling_down / server_busy	服务暂不可用或账号冷却中，请稍后重试。
502 video_link_identity_failed / video_link_account_changed	原账号无法核对，或账号设置刚发生变化，请联系管理员检查。
502 video_link_settings_failed	无水印设置未确认，需由管理员刷新账号状态。
502 video_link_resource_pending / video_link_resource_failed	无水印资源暂未就绪或获取失败。临时错误最多自动重试一次，不会重新生成视频。
502 video_link_result_unavailable / video_link_refresh_failed	原视频资源暂不可用或链接无法刷新，保留任务编号。

示例代码

下载 Python 调用示例 ↗ · 下载 OpenAPI 文档 ↗

本接口是独立协议，不声称与 V6K、飞拓或 New API 直接兼容。尚未提供客户自助充值、自动计费或回调推送。