AI 视频 API 报错怎么解决?提交被拒、任务失败、内容审核逐条对照(2026)
视频生成接口的报错分两类:提交时直接被拒,和任务轮询到 FAILED。本文按 cocodot 视频接口返回的报错原文逐条讲原因和改法,并给出一个只重试该重试的错误、不白白重复提交的轮询脚本。
1. 先分清:提交被拒,还是任务失败
cocodot 的视频接口是异步的:POST https://cocodot.co/api/ai/video/generations 提交,返回任务 ID;之后轮询 GET https://cocodot.co/api/ai/video/generations/{id},状态是 PENDING(生成中)、SUCCEEDED(成功,带 videoUrl)或 FAILED(失败,带 error)。报错因此有两个出口。提交时被拒:接口直接返回 HTTP 错误码和 message,参数类错误在建任务之前就会拦下,不会生成任务。任务失败:提交时返回了任务 ID,轮询到 FAILED,失败原因在 error 字段。排错第一步就是看你的报错来自哪一个出口:提交时的 400 基本都能靠改请求解决;任务失败要看 error 的原文再决定是改内容还是稍后重试。日志里请把任务 ID、提交的完整参数、HTTP 状态码和报错原文记在一起,出了问题找客服时直接给任务 ID。
2. 400「不支持的字段」:每家只认自己的字段
三家视频模型的请求格式不一样,cocodot 对每家只放行一组字段,多传了就会返回「视频请求包含不支持的字段,允许字段: …」,冒号后面列的就是这个型号当前接受的字段。按 cocodot 当前接口:Seedance 系列认 model、content、resolution、duration;可灵认 model、content、prompt、mode、duration、sound;海螺认 model、content、prompt、resolution、duration,海螺 2.3 Fast 另外多认一个 first_frame_image。常见的踩坑是把一家的请求模板直接改个 model 拿去调另一家,比如给可灵传了 resolution,或给 Seedance 传了 prompt。改法很简单:以报错里列出的允许字段为准删减。另外,model 填错会返回「不支持的视频型号」,可用的视频型号名以 GET https://cocodot.co/api/ai/video/models 返回的 id 为准。
// Seedance
{"model": "seedance-2.5", "content": [{"type": "text", "text": "清晨的港口,镜头缓慢推近"}], "resolution": "720p", "duration": 5}
// 可灵
{"model": "kling-v3", "prompt": "雨夜街道,霓虹倒影", "mode": "std", "duration": 5, "sound": "off"}
// 海螺 2.3 Fast(图生视频)
{"model": "hailuo-2.3-fast", "prompt": "镜头缓慢推近", "first_frame_image": "https://…/frame.png", "resolution": "768P", "duration": 6}3. 时长、分辨率、档位:只开放列表里的组合
cocodot 只放行逐档核过价格的参数组合,不在范围内的会在提交时拒绝,不建任务、不扣费。常见报错有几种:「XX 当前仅开放 480p/720p」这类,说明分辨率不在该型号开放的范围;「XX 当前仅开放 … 秒」,说明时长不在开放的档位;「仅支持 std/pro 模式」是可灵的 mode 填错了;「该参数组合暂不开放」说明单个参数都合法,但组合起来不在开放的价格表里。还有两条和时长格式有关:「duration 必须是正整数秒」—— 数字 5 和字符串 "5" 都可以,5.5 或 "5s" 不行;可灵按秒计费,不传 duration 会返回「按秒计费,请指定 duration(秒)」。最省事的做法是每次改参数前先请求 GET https://cocodot.co/api/ai/video/models,读每个型号的 allowed(可选分辨率、时长、档位),在你自己的代码里提前校验,不合法的参数根本不发出去。
4. 海螺 Fast 的首帧图、content 里放图片
可灵和海螺在 cocodot 上只接受文本形式的 content,往 content 里放图片或视频会返回「该型号暂不支持在 content 里传图片或视频;海螺 2.3 Fast 的首帧图请用 first_frame_image 字段传入」。海螺 2.3 Fast 是图生视频,首帧图必须放在 first_frame_image 字段:填公网可访问的 http(s) 图片链接,或 data:image/ 开头的 base64,整体不超过 10MB。链接里带空格、不是 http(s) 协议、base64 没有 data:image/ 前缀,都会被拒,报错是笼统的「视频任务提交失败,本次未扣费。请检查参数(分辨率、时长、图片或视频引用)后重试」。排查顺序:先在浏览器无痕窗口里打开这个图片链接,确认不需要登录就能看到;再确认链接没有被你的代码多拼了空格或换行;用 base64 时检查前缀和大小。海螺两个型号的接法细节见 /hub/hailuo-2-3-api。
5. Seedance:提示词里的 --rs、--dur 会被拒
有些 Seedance 教程教人在提示词末尾写「--rs 1080p --dur 12」这类文本命令来指定分辨率和时长。在 cocodot 上,Seedance 提示词里出现这类 --参数会直接返回「提示词里不支持 --参数写法,分辨率、时长请用 resolution、duration 字段指定;其它参数暂不开放」。规格必须写在字段里,提交前才能按字段算出这条视频的预估费用。改法:把分辨率写进 resolution 字段、时长写进 duration 字段,提示词里只留画面描述。被拦的不只是 --rs 和 --dur,--ratio、--fps、--seed、--watermark 等文本参数同样不支持;如果你的提示词是从别的平台批量导出的,先用正则把「--字母」开头的片段清掉再提交。Seedance 各版本的可选规格和计费方式见 /hub/seedance-2-5-api。
6. 内容审核未通过:改内容,别原样重投
「视频内容未通过安全审核,本次未扣费,请调整内容后重试。」可能在两个地方出现:提交时直接返回 400,或者提交成功、生成过程中任务以 FAILED 结束、error 里是这句。两种情况都没有扣费,但都说明这次的提示词或素材(包括首帧图、参考视频)没有通过审核。内容没改就再提交,被审核的东西并没有变,还会占用你的并发名额。处理思路:先看提示词里有没有涉及真实人物、暴力、敏感场景的描述,换成更中性的说法;再检查首帧图和参考素材本身;如果提示词很干净但生成中途被拦,可以调整镜头和动作描述后再试。审核的具体标准不在本文范围内,哪些内容能通过审核,我们不做承诺。
7. 429、503、余额不足、并发上限、401 / 403
429「视频生成请求太频繁,本次未扣费,请稍后再试」和503「视频服务暂时不可用,本次未扣费,请稍后重试」是该退避重试的:等几秒到几十秒、每次加倍,设一个总次数上限。「钱包余额不足:这条视频预估约 $…,请先充值(体验额度不支持视频)」说明这条的预估金额超过了可用余额(正在生成中的任务已经各自预扣了预估金额);视频不能使用 $0.5 体验额度,要先充值,充值支持支付宝 / 微信支付(人民币)、USDT / USDC。「同时最多 3 条视频在生成,请等已提交的完成后再提交」说明你同时在生成中的任务到了上限,等前面的完成或失败再提交,批量任务要在你自己这边排队。401 是 key 缺失或无效(missing api key / invalid api key),检查 Authorization: Bearer cocodot-… 的写法;403 是账户层面的条件没满足,常见的是还没完成实名 L1,报错里会附完成认证的链接。
8. 一个不白花钱的轮询与重试写法
视频任务失败不扣费,但改完再提交、成功了就是一条新任务,照常计费;同一个请求失败后被你的脚本无脑重投十次,最好的情况是浪费时间,最坏的情况是在你没注意时成功了好几条。下面的写法按报错分流:400 一律不重试,直接把报错原文打出来让人改参数;429 / 503 退避重试,有次数上限;任务 FAILED 时,只有通用的「视频生成失败」才重试,而且最多一两次,审核类不重试。轮询间隔不用太密,十几秒一次足够;拿到 SUCCEEDED 后尽快把 videoUrl 下载转存,链接会过期。这是一条别处抄不到的干货:按 cocodot 视频接口实际返回的文案分流,而不是按 HTTP 码一刀切。
import time, requests
BASE = "https://cocodot.co/api/ai/video/generations"
H = {"Authorization": "Bearer cocodot-..."}
def submit(body, tries=4):
for i in range(tries):
r = requests.post(BASE, json=body, headers=H, timeout=90)
if r.ok:
return r.json()["id"]
if r.status_code in (429, 503):
time.sleep(5 * 2 ** i)
continue
raise RuntimeError(f"{r.status_code} {r.text}") # 400/401/403:改请求,不重试
raise RuntimeError("多次 429/503,稍后再跑")
def run(body, max_regen=1):
for attempt in range(max_regen + 1):
tid = submit(body)
while True:
time.sleep(15)
t = requests.get(f"{BASE}/{tid}", headers=H, timeout=30).json()
if t["status"] == "SUCCEEDED":
return t["videoUrl"] # 尽快下载转存
if t["status"] == "FAILED":
break
err = t.get("error") or ""
print("task", tid, "failed:", err)
if err != "视频生成失败,本次未扣费,请稍后重试。":
raise RuntimeError(err) # 审核或未知错误先人工检查
raise RuntimeError("多次生成失败:检查参数或内容")cocodot 视频接口常见报错对照(报错原文以接口实际返回为准)
| 报错(摘要) | 出现在哪 | 原因 | 怎么办 |
|---|---|---|---|
| 视频请求包含不支持的字段,允许字段: … | 提交 400 | 请求体里有该型号不认的字段 | 按报错列出的允许字段删减 |
| 当前仅开放 … / 该参数组合暂不开放 | 提交 400 | 分辨率、时长或档位不在开放范围 | 查 GET /api/ai/video/models 的 allowed 后改参数 |
| 该型号暂不支持在 content 里传图片或视频 | 提交 400 | 可灵 / 海螺的 content 只收文本 | 海螺 2.3 Fast 的首帧图改用 first_frame_image |
| 提示词里不支持 --参数写法 | 提交 400 | Seedance 提示词里写了 --rs、--dur 等 | 删掉文本参数,改用 resolution、duration 字段 |
| 视频任务提交失败,本次未扣费 | 提交 400 | 参数或图片 / 视频引用不被接受 | 检查分辨率、时长、图片链接或 base64 |
| 视频内容未通过安全审核,本次未扣费 | 提交 400 或任务 FAILED | 提示词或素材未通过审核 | 改内容后再提交,不要原样重投 |
| 视频生成请求太频繁 / 服务暂时不可用 | 提交 429 / 503 | 请求过密或服务暂时不可用 | 退避后重试 |
| 视频生成失败,本次未扣费,请稍后重试 | 任务 FAILED | 生成过程失败,原因未细分 | 稍后重试一两次,多次失败再查参数或内容 |