常见问题与重试策略
重试与超时
Q：查询超时了怎么办？
查询超时表示这次请求没有及时得到响应，不代表任务失败。使用同一个任务 ID，等待 10 秒后重新发送查询请求。
sleep 10
curl https://api.maomaotoken.com/v1/videos/TASK_ID \
-H "Authorization: Bearer YOUR_API_KEY"将 TASK_ID 替换为创建响应中的 id。建议每个视频任务每隔 10 秒查询一次，收到 completed 或 failed 后停止查询。
Q：创建请求超时了怎么办？
创建请求超时不代表任务未创建。直接再次提交可能产生重复任务和额外费用。
- 检查客户端是否已保存创建响应中的
id，并核对控制台中的任务或请求记录。 - 如果找到任务 ID，使用原 ID 继续查询。
- 如果无法确认任务是否已受理，保留请求时间、模型和错误信息，联系技术支持核对后再决定是否重新提交。
Q：收到错误后可以直接重试吗？
先区分请求错误和任务失败：
- 参数错误：根据
code和message修正请求，再重新提交。 - 认证或权限错误：检查密钥、账户和模型权限，修复后再提交。
- 查询超时或临时异常：保留原任务 ID，间隔 10 秒重试查询。
- 任务返回
failed：查看error，确认原因后再决定是否创建新任务。
创建请求的超时或临时异常，应先核对是否已受理。不要给创建接口设置无条件自动重试。
任务状态与进度
Q：为什么没有任务 ID？
请求未通过认证、参数校验或未被受理时，可能不会返回任务 ID。请检查 HTTP 状态码和错误响应中的 code、message。
如果是连接中断或超时，不能仅凭“没有收到 ID”判断任务未创建，请按上面的创建超时说明处理。
Q：为什么进度不增长？
progress 是 0–100 的整数，用于表示任务的处理进度。进度可能随处理阶段更新，并在同一阶段内保持不变。
例如，连续两次查询可能都返回以下状态。这不代表任务已经停止处理：
{
"status": "in_progress",
"progress": 30
}不要根据进度值估算剩余时间。是否完成以 status 为准：completed 表示成功，failed 表示失败。
Q：任务长时间处于 in_progress 怎么办？
视频生成时间会因模型、时长和素材复杂度而不同。继续每隔 10 秒查询一次，高频查询不会加快生成。
如果任务长时间没有状态变化，请向技术支持提供任务 ID、创建时间和最近一次查询结果。不要仅因等待较久就重复创建。
参考素材与并发
Q：为什么素材 URL 无法使用？
请检查以下几点：
- 使用公网 HTTPS 链接，无需登录或额外认证即可访问。
- 链接尚未过期，并能在任务处理期间保持有效。
- 地址返回真实图片、视频或音频，不是网页、登录页或错误页。
- 素材类型、数量和组合符合所选模型的能力限制。
前置检查不会下载素材，地址通过检查后仍可能在实际取用时失败。浏览器中能打开，也不一定表示服务端可以直接访问。
Q：视频任务可以使用 Base64 图片吗？
不支持。视频请求中的图片、视频和音频参考素材均需使用公网 HTTPS 链接；不要直接传入 Base64 数据或以 data: 开头的内嵌素材。
素材结构与示例见「参考素材要求」。
Q：可以同时处理多个任务吗？
可以，但需要遵守账户的并发和请求频率限制。请分别保存每个任务的 id，每个任务每隔 10 秒查询一次。
同一个任务的查询请求尚未结束时，不要再发起重叠查询；收到 completed 或 failed 后停止该任务的轮询。
费用与配额
Q：前置校验失败会扣费吗？
不会。前置校验失败时任务未创建，不产生视频生成费用。
任务已受理后的费用，以账户中的实际结算记录为准。查询超时不代表任务失败，也不能据此判断是否扣费。
Q：重复创建会产生多次费用吗？
每次被受理的创建请求都会产生独立任务，可能分别产生费用。创建成功后请立即保存响应中的 id，后续使用同一个 ID 查询。
不要通过重复发送 POST /v1/videos 获取进度，也不要把“创建成功”当成“视频已生成”。
连接与认证
Q：收到 401 或 403 怎么办？
检查 API 密钥是否有效、是否具有模型访问权限，以及请求头是否使用以下格式：
Authorization: Bearer YOUR_API_KEY将 YOUR_API_KEY 替换为实际密钥。创建和查询都需要身份验证；查询任务时请使用有权访问该任务的账户密钥。
Q：收到 429 怎么办？
请根据错误信息降低请求频率或并发量，等待后重试。对于已有任务，保留任务 ID，并继续按每隔 10 秒一次的建议查询。
如果创建请求是否已受理不明确，请先核对任务记录，避免重复提交。
结果与首次接入
Q：任务完成后怎么拿到视频？
当 status 为 completed 时，从查询响应中的 video_url 获取下载地址，并及时保存视频。下载方法见「视频保存与下载」。
Q：视频链接会一直有效吗？
视频链接可能有有效期，不应作为永久存储地址。生成完成后请尽快下载，并保存到自己的存储中。
具体保留规则见「视频保存与下载」；如果下载失败，请保留任务 ID 和错误信息。
Q：首次接入应该怎么测试？
先选择已开通的模型，按其支持的时长和画幅提交一个简单的文生视频请求。创建成功后保存 id，每隔 10 秒查询一次，直到任务成功或失败。
首次测试无需加入参考素材。确认创建、查询和下载流程可用后，再逐步加入图片、视频或音频参考。完整请求示例见「快速开始」和「创建视频任务」。