统一异步任务：提交、轮询与结果生命周期

小白：提交与轮询

通用异步包装保留原 POST 路径，只在前面加 /async。调用前先在令牌管理创建本站 API Key，再从模型广场复制当前 Key 分组可用、且支持目标原路径的精确模型 ID。

Copyexport BASE_URL="https://api.tu-zi.com"
export API_KEY="你的本站 API Key"
export MODEL_NAME="从模型广场复制的精确模型 ID"

submit=$(curl -sS "$BASE_URL/async/v1/videos"   -H "Authorization: Bearer $API_KEY"   -H "Content-Type: application/json"   -d @- <<JSON
{"model":"$MODEL_NAME","prompt":"雨后城市的短镜头"}
JSON
)
task_id=$(printf '%s' "$submit" | jq -r .id)

curl -sS "$BASE_URL/get-async?id=$task_id"   -H "Authorization: Bearer $API_KEY"

上面的最后一条 curl 只演示一次查询。实际应用要读取 status，对非终态按下文的退避方式继续查询，不能执行一次就认定任务完成。

提交成功通常返回 202、任务 id 与 queued 状态。查询必须使用创建任务的用户和令牌权限，不能把任务 ID 当作公开下载地址。上面的视频路径会形成两层任务：先查询通用异步任务；外层 completed 只表示内部 POST /v1/videos 已经返回。如果 result 中有视频任务 ID，还要按视频生成页面继续查询内层任务，直到它自己的成功或失败终态。

状态机与终态

把 queued、not_start、submitted、in_progress 视为非终态；failure 和 completed 为外层终态，expired 表示结果已清理。轮询采用带抖动的退避，例如 1、2、4、8 秒后稳定到上限，并设置总截止时间。不要每秒无限轮询；前端刷新也不应创建新的生成任务。

结果信封

JSON 上游结果会放在 result 字段；二进制结果以 Base64 返回，并带 encoding: "base64"、原始 content_type 和 status_code。客户端要先检查外层 status，再验证内层状态码与对象结构。完成后立即把需要长期保存的媒体流式复制到自己的对象存储。

不支持的包装

通用异步拒绝 GET、SSE、stream:true、模型列表、/v1/files、/v1/realtime 和 Gemini 流式生成。原生视频、Kling、Suno 等任务协议可能拥有自己的创建与查询路径，不应与通用任务 ID 混用。

幂等、失败与计费

网络在提交响应返回前断开时，任务可能已经创建。客户端应保存业务请求指纹并先查已有任务，避免盲目重发。队列满、参数错误和鉴权错误不可无限重试；临时 429/5xx 才适合有限退避。预扣、最终结算和退款可能跨越任务生命周期，需在终态后用任务 ID、Request-ID 与消费日志核对。

专家运维

监控队列深度、排队时长、执行时长、成功率、失败原因、结果大小、过期率和存储剩余空间。结果写入必须有大小上限并采用流式 I/O，避免整份媒体驻留内存。清理策略应保护运行中任务，低磁盘时拒绝新任务而不是删除仍需交付的结果。