图像与视频生成 API 指南

图像 API 的关键参数

文本生成图像通常包含提示词、尺寸、张数、质量、风格和随机种子。图像编辑还需要输入图、蒙版和保真度。统一平台应把公共参数标准化，并通过扩展字段承载模型特有能力。

视频 API 的关键参数

视频请求通常包含提示词、首帧或参考图、宽高比、生成时长、分辨率、镜头运动和是否生成音频。生成成本与时长和质量高度相关，提交前应向用户展示预估费用和最大等待时间。

异步任务状态机

queued → processing → succeeded
                    ↘ failed
                    ↘ cancelled

创建任务后立即返回任务 ID。客户端可以轮询状态，也可以等待 Webhook。任务记录应保存上游任务 ID、用户 ID、模型、参数摘要、价格快照、状态变化时间和输出资源地址。重试创建任务时必须使用幂等键，防止重复扣费。

可靠的 Webhook 回调

回调应包含事件 ID、任务 ID、状态、时间戳和签名。接收方先验证签名和时间窗口，再使用事件 ID 去重。业务处理失败时返回非 2xx，让发送方按退避策略重试；耗时工作应放入内部队列，避免阻塞回调响应。

内容安全、版权与文件存储

平台应根据业务地区和模型规则处理违法内容、未授权人物形象、隐私信息及版权风险。输入素材和生成结果应设置明确保存期限。临时下载 URL 使用短期签名，存储桶默认私有，不在日志中记录完整敏感 URL。

生产优化

将聊天请求与媒体任务分离队列；限制单用户并发；对上传文件做 MIME、尺寸和病毒检查；为长任务设置超时与取消；记录任务各阶段耗时；在上游失败时明确区分可重试错误和永久错误。

常见问题

为什么视频 API 不适合保持一个长 HTTP 请求？

生成可能持续数分钟，长连接更容易受代理超时和网络波动影响，异步任务更可靠。

图片 URL 可以永久使用吗？

多数上游 URL 有有效期。生产系统应在授权范围内及时转存到自己的对象存储。