{"openapi":"3.1.0","info":{"title":"豆包视频中转 API","version":"0.6.0","description":"异步视频任务。当前协议为本项目自定义协议，不声称与其他网关直接兼容。视频结果只返回上游链接。"},"servers":[{"url":"/"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer"}},"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"seconds":{"type":"integer","minimum":4,"maximum":15,"description":"请求的视频时长（秒）"},"status":{"type":"string","description":"queued、preparing、uploading、submitting、confirming、rescuing、running、awaiting_confirmation、rescue_waiting、complete、failed、paused、unknown、cancelled、legacy"},"status_label":{"type":"string","description":"展示用中文状态；按status编写程序逻辑"},"attempt_count":{"type":"integer","minimum":1,"description":"本任务已分配的账号数量"},"error":{"type":"object","properties":{"code":{"type":"string"},"category":{"type":"string"},"message":{"type":"string"}}},"attention":{"type":"object","description":"结果待核对时的说明"},"result_error":{"type":"object","description":"视频已完成但链接暂未就绪，请继续查询原任务，不要重新生成","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"video_url":{"type":["string","null"],"description":"与/result相同的已解析链接；不会降级返回旧水印地址"},"needs_operator":{"type":"boolean"}}}}},"paths":{"/healthz":{"get":{"summary":"服务健康与生成开关","security":[],"responses":{"200":{"description":"服务在线","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"generation_enabled":{"type":"boolean"}}}}}}}}},"/readyz":{"get":{"summary":"可受理检查（账号、额度、磁盘、调度心跳）","security":[],"responses":{"200":{"description":"可受理","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"当前不可受理","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}}}}}}}}},"/v1/images":{"post":{"summary":"上传一张参考图片","description":"原始二进制，单张10MiB、2400万像素、最长边12000；每客户累计1GiB、全局10GiB。闲置48小时后自动清理；未完成任务引用图片保留，完成后再保留48小时。图片ID仅所属客户可用，过期需重新上传。","requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"图片已保存","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"width":{"type":"integer"},"height":{"type":"integer"},"bytes":{"type":"integer"}}}}}},"400":{"description":"请求失败，读取 error.code 判断原因"},"401":{"description":"请求失败，读取 error.code 判断原因"},"413":{"description":"请求失败，读取 error.code 判断原因"},"415":{"description":"请求失败，读取 error.code 判断原因"}}}},"/v1/videos":{"post":{"summary":"提交视频任务","description":"返回任务编号，后续轮询。明确提交失败可按管理员策略自动换号，任务编号保持不变；发送结果未知不会自动换号重发。当天受理上限按北京时间计算；同一提交标识与内容重试不会新增任务。","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{8,100}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":20000},"image_ids":{"type":"array","maxItems":9,"uniqueItems":true,"items":{"type":"string","format":"uuid"}},"ratio":{"type":"string","enum":["9:16","16:9","1:1","4:3","3:4","21:9"],"default":"9:16"},"seconds":{"type":"integer","minimum":4,"maximum":15,"description":"视频时长，整数秒。推荐明确传入；不传时沿用旧行为，不指定时长。测试页默认10秒。"},"force15s":{"type":"boolean","default":false,"deprecated":true,"description":"兼容旧参数；true表示15秒，若同时传seconds则必须为15。"},"useFast":{"type":"boolean","default":true}}}}}},"responses":{"202":{"description":"任务受理","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"seconds":{"type":"integer","minimum":4,"maximum":15,"description":"请求的视频时长（秒）"},"status":{"type":"string","description":"queued、preparing、uploading、submitting、confirming、rescuing、running、awaiting_confirmation、rescue_waiting、complete、failed、paused、unknown、cancelled、legacy"},"status_label":{"type":"string","description":"展示用中文状态；按status编写程序逻辑"},"attempt_count":{"type":"integer","minimum":1,"description":"本任务已分配的账号数量"},"error":{"type":"object","properties":{"code":{"type":"string"},"category":{"type":"string"},"message":{"type":"string"}}},"attention":{"type":"object","description":"结果待核对时的说明"},"result_error":{"type":"object","description":"视频已完成但链接暂未就绪，请继续查询原任务，不要重新生成","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"video_url":{"type":["string","null"],"description":"与/result相同的已解析链接；不会降级返回旧水印地址"},"needs_operator":{"type":"boolean"}}}}}},"400":{"description":"请求失败，读取 error.code 判断原因"},"401":{"description":"请求失败，读取 error.code 判断原因"},"409":{"description":"请求失败，读取 error.code 判断原因"},"429":{"description":"请求失败，读取 error.code 判断原因"},"503":{"description":"请求失败，读取 error.code 判断原因"}}}},"/v1/videos/{id}":{"get":{"summary":"查询任务","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"任务状态","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"seconds":{"type":"integer","minimum":4,"maximum":15,"description":"请求的视频时长（秒）"},"status":{"type":"string","description":"queued、preparing、uploading、submitting、confirming、rescuing、running、awaiting_confirmation、rescue_waiting、complete、failed、paused、unknown、cancelled、legacy"},"status_label":{"type":"string","description":"展示用中文状态；按status编写程序逻辑"},"attempt_count":{"type":"integer","minimum":1,"description":"本任务已分配的账号数量"},"error":{"type":"object","properties":{"code":{"type":"string"},"category":{"type":"string"},"message":{"type":"string"}}},"attention":{"type":"object","description":"结果待核对时的说明"},"result_error":{"type":"object","description":"视频已完成但链接暂未就绪，请继续查询原任务，不要重新生成","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"video_url":{"type":["string","null"],"description":"与/result相同的已解析链接；不会降级返回旧水印地址"},"needs_operator":{"type":"boolean"}}}}}},"401":{"description":"请求失败，读取 error.code 判断原因"},"404":{"description":"请求失败，读取 error.code 判断原因"}}}},"/v1/videos/{id}/result":{"get":{"summary":"刷新已完成任务的视频链接","description":"返回 JSON 中的 video_url，不代理视频文件。复用账号已确认的无水印状态；临时资源错误最多自动重试一次，不重新生成视频。502 的 error.code 区分身份核对、设置、原结果与无水印资源错误，详见 /docs。链接有效期以实际情况为准。下载链接时不要附带 API Key。","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"上游链接","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"video_url":{"type":"string","format":"uri"}}}}}},"401":{"description":"请求失败，读取 error.code 判断原因"},"404":{"description":"请求失败，读取 error.code 判断原因"},"409":{"description":"请求失败，读取 error.code 判断原因"},"502":{"description":"请求失败，读取 error.code 判断原因"}}}}}}