媒体任务的提交与查询：图片视频接入的正确姿势

2026-11-12 · 媒体模型 · 异步任务 · 接入

聊天模型可以同步等结果，媒体模型不行：一次图片或视频生成可能跑几十秒到几分钟。所以媒体协议设计成两步：先提交拿任务号，再按任务号取结果。

提交

POST /v1/media/generate，请求里带模型 ID、提示词与生成参数。参考图、时长、画幅、清晰度都放在参数对象里；回调地址是顶层字段，不要放进参数对象，放进去不会生效。

查询

GET /v1/media/status?task_id=。轮询建议从 2 秒起步，按 2 → 4 → 8 秒退避，设一个总时长上限。不要固定 1 秒轮询，那只是在浪费配额。

回调

如果配置了回调地址，任务到达终态时平台会主动推送结果，失败会按间隔重试若干次。回调到达即代表任务已有结论，此时不需要再轮询。

失败处理

媒体任务的失败分两类：参数问题（提示词触发风控、参考图不可读）与执行问题（上游超时）。前者不要重试，改提示词再提交；后者可以重提一次，并记录task_id 以便对账。

结果落地

1. 结果链接可能是临时地址，落盘保存到自己的对象存储。
2. 把 task_id 与业务 ID 关联存库，方便返工时定位。
3. 同一分镜的多次尝试都保留记录，用于分析返工率。

媒体模型的清单在 协议与模型清单；按次计费的成本控制见 按次计费的三个隐性成本。