视频生成通常不是一次 HTTP 请求等待到文件返回，而是“创建任务、查询状态、下载结果”的异步流程。接入时如果没有保存任务 ID、限制轮询和处理幂等，很容易重复扣费或生成重复视频。
先确认接口形态
从当前模型页面和 API 文档确认：
- 模型支持文生视频、图生视频还是视频编辑。
- 创建任务需要哪些输入和上传方式。
- 是否返回任务 ID。
- 查询状态和下载结果使用什么端点。
- 时长、分辨率、宽高比、音频等参数是否支持。
查看当前视频模型与价格。不要把其他平台的请求字段默认套到当前模型。
正确的任务状态机
应用至少处理这些状态：
created -> queued -> running -> succeeded
\-> failed
\-> cancelled
客户端观察时间超过上限 -> timed_out（应用侧状态）服务端任务可能仍在运行，即使客户端已经超时。重新创建任务前，应先用原任务 ID 查询，避免把“查询超时”误判成“任务不存在”。
通用接入骨架
端点和字段必须从当前 API 文档复制。下面只展示应用结构：
import time
CREATE_URL = "从文档复制的任务创建端点"
STATUS_URL_TEMPLATE = "从文档复制的状态查询端点，包含任务ID占位符"
def create_video_task(payload):
response = authenticated_post(CREATE_URL, payload, timeout=30)
return response["task_id"]
def wait_for_video(task_id, max_wait_seconds=600):
deadline = time.monotonic() + max_wait_seconds
interval = 3
while time.monotonic() < deadline:
result = authenticated_get(
STATUS_URL_TEMPLATE.replace("{task_id}", task_id),
timeout=20,
)
if result["status"] == "succeeded":
return result
if result["status"] in {"failed", "cancelled"}:
raise RuntimeError(result)
time.sleep(interval)
interval = min(interval + 2, 15)
raise TimeoutError(f"task {task_id} is still not finished")authenticated_post 和 authenticated_get 代表你自己的 HTTP 封装。示例不假设 AI快站当前视频接口一定使用 task_id 或这些状态名称，应按真实响应映射。
幂等和重复任务
为每个业务任务生成自己的唯一 ID，并保存：
- 业务任务 ID。
- 上游任务 ID。
- 请求模型和关键参数。
- 创建时间和最后查询时间。
- 当前状态和结果地址。
- 已尝试次数。
当用户刷新页面或队列消费者重启时，先查询已有任务，不要直接再次创建。只有当前接口明确支持幂等键时，才把业务 ID 放入对应请求头或字段。
轮询不要这样写
以下做法会增加故障和成本：
- 每秒无限轮询。
- 遇到所有 4xx、5xx 都立即重试。
- 客户端超时后直接创建新任务。
- 不保存任务 ID，只把任务放在内存中。
- 结果下载失败就重新生成视频。
推荐区分创建超时、状态查询超时、任务失败和结果下载失败。下载失败通常只需要重试下载，不需要重新生成。
如何验收视频质量
固定提示词、参考图和受支持参数，分别检查：
| 维度 | 记录方式 |
|---|---|
| 指令完成 | 主体、动作、镜头和场景是否出现 |
| 时间一致性 | 人物、服装、物体在连续帧中是否稳定 |
| 运动质量 | 动作是否自然、是否出现跳变或穿模 |
| 画面质量 | 清晰度、压缩、闪烁和水印情况 |
| 任务性能 | 排队时间、生成时间、失败率和下载时间 |
| 完整成本 | 成功任务、失败任务和重复任务的总费用 |
先用较短时长和较低成本配置验证构图及动作，再提高正式输出规格。不要只比较一条成功样片。
结果保存与过期
如果返回临时下载地址：
- 生成成功后立即下载到自己的对象存储。
- 校验状态码、
Content-Type、文件大小和视频时长。 - 保存上游任务 ID与自己的存储地址。
- 下载失败只重试下载，达到上限后告警。
不要把临时 URL 直接发给长期用户，也不要在日志中保存包含签名参数的完整下载地址。
常见错误
创建成功但一直 queued
记录模型、任务 ID、创建时间和查询响应。检查模型维护、队列状态、账号额度和并发限制，不要持续提高轮询频率。
状态查询返回 404
确认任务 ID、状态端点和账号是否一致。部分任务查询路径与创建路径不在同一前缀下，不能自行拼接。
图生视频输入失败
检查图片格式、大小、可访问性和上传方式。外部图片 URL 可能因防盗链、过期或访问权限导致服务端无法读取。
视频生成成功但下载失败
把生成和下载视为两个阶段。保存原任务 ID，重新获取或重试结果地址，不要立即重新创建生成任务。
上线前检查
- 任务创建、查询和结果端点均来自当前文档。
- 业务任务 ID 与上游任务 ID 已持久化。
- 轮询间隔、总等待时间和重试次数都有上限。
- 查询超时不会自动重复创建任务。
- 临时结果会转存并校验文件。
- 固定题集覆盖动作、人物和镜头失败案例。
- 成本统计包含失败与重复任务。
继续阅读大模型 API 成本估算和生产上线检查清单，把媒体任务纳入队列、告警和预算保护。