指南

异步媒体任务：提交、查询与结果验收

预览指南

粘贴给 AI，帮助理解文档并完成接入。仅包含文档与示例，不包含真实密钥。

# 异步媒体任务：提交、查询与结果验收

使用模型原生任务接口；通用 /async 已停用（410），/get-async 已移除（404）。提交成功后按对应协议查询到终态并验证媒体。

## 小白：先选模型的任务协议

从模型广场复制精确模型 ID，使用该模型快速上手中的提交示例。只有响应真正返回任务 ID 时，才进入任务查询流程。HTTP 200 只说明本次 HTTP 请求成功，不表示图片、视频或音频已生成。

## 已停用的通用包装

`/async/*` 已停用，鉴权通过后返回 HTTP 410 `endpoint_deprecated`；`/get-async` 已移除，返回 404。不要给任意路径加 `/async`，也不要套用旧的双层任务或 Base64 结果信封。普通同步和 SSE 请求保持原有协议。

## 提交与查询配对

| 提交协议 | 查询入口 | 成功 / 失败终态 |
| --- | --- | --- |
| 统一视频或异步图片 | `GET /v1/videos/{task_id}` | 按实际适配器响应解析；常见 completed / failed |
| FLUX 原生 flux-3-image | `GET /flux/v1/get_result?id={task_id}` | Ready / Error |
| Suno v2 | `GET /suno/v2/fetch/{task_id}` | data.status: SUCCESS / FAILURE |
| Kling | `GET /kling/v1/{category}/{kind}/{task_id}` | data.status: SUCCESS / FAILURE |
| Midjourney | `GET /mj/task/{task_id}/fetch` | status: SUCCESS / FAILURE |

Kling 的 category、kind 和 Midjourney 模式前缀须与提交对应。不同协议的 ID、响应字段与状态大小写不能混用。查询应使用创建任务账号及相应权限的 Key。

## 查询与下载示例

下面只查询已创建的 FLUX 任务，不会再次发起生成：

```bash
curl --fail-with-body "$BASE_URL/flux/v1/get_result?id=$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"
```

Pending 表示继续等待；Ready 后读取 result.sample 下载图片；Error 表示生成失败，应记录 error 并停止轮询。视频内容入口为 `GET /v1/videos/{task_id}/content`，成功响应是媒体字节，不能按 JSON 解析。结果链接和保存期依实际协议与存储配置，完成后及时保存。

## 退避、超时与计费

以 1、2、4、8 秒等间隔退避，设置最大间隔和总截止时间。连接超时可能发生在上游接受请求之后，不能自动重复提交。保存任务 ID 和请求 ID；没有任务 ID 时可按请求 ID 查消费日志。预扣和结算不等于生成成功。

## 专家：结果恢复与排障

`GET /v1/images/generations/result?request_id=...` 用于恢复图片请求的已保存链接，不是通用任务查询。processing_or_not_found 不能区分处理中、记录不存在、无权访问或无可恢复链接，不能据此无限轮询或重发。成功验收必须确认终态、结果字段和实际可读取媒体；仅有任务 ID 不算成功。

## 适用场景

- 长耗时媒体与批处理请求
- 避免客户端连接超时并可靠取得结果

## API 路径

- /v1/videos
- /v1/videos/{task_id}
- /flux/v1/get_result
- /suno/v2/fetch/{task_id}

## 关联指南

- [本站 API 端点与能力矩阵](https://api.tu-zi.com/docs/use-cases/endpoint-matrix): 先在模型广场确认精确模型与已开放端点，再按本页选择协议；路由存在只表示网关认识该路径，不表示每个模型或渠道都支持。
- [视频生成模型与异步 API 指南](https://api.tu-zi.com/docs/use-cases/video-generation): 视频生成应按异步任务系统设计：幂等提交、持久化任务 ID、有界轮询或验签回调、终态处理、结果转存与内容审核缺一不可。
- [文件与媒体输入、输出及生命周期](https://api.tu-zi.com/docs/use-cases/files-media): 本站 `/v1/files` 当前未实现；文件必须按目标模型和端点支持的方式随请求提交，所有输入与结果 URL 都应视为有权限和生命周期的外部资源。
- [计费、用量与成本核对](https://api.tu-zi.com/docs/use-cases/billing-usage): 价格以模型广场和当前分组为准；请求侧保存模型、路径、Request-ID、usage 或任务 ID，再用消费日志核对最终结算，不能只看提交时余额变化。

## 常见问题

### 还能给请求加 /async 吗？

不能，旧接口返回 410；选择该模型原生任务协议。

### 查询返回 200 就完成了吗？

不能只看 HTTP 状态，须确认任务成功终态并验证媒体。

### 超时后能重发吗？

先查已有任务和请求日志，避免创建重复收费任务。

## 参考来源

- OpenAI API Reference: https://developers.openai.com/api/reference/overview
- Gemini API Errors: https://ai.google.dev/gemini-api/docs/api-errors
- Claude API Errors: https://platform.claude.com/docs/en/api/errors

## 文档来源

来源: https://api.tu-zi.com/docs/use-cases/async-tasks

核验日期: 2026-11-02

本文为文档接入参考。厂商原生接口与本站接口可能不同；请结合对应 API Reference 和模型广场确认本站地址、鉴权、模型 ID、分组与参数。本文不表示所有模型或上游服务均已通过实时调用验收。仅包含文档与示例，不包含当前用户的密钥或请求记录。

直接答案使用模型原生任务接口；通用 /async 已停用（410），/get-async 已移除（404）。提交成功后按对应协议查询到终态并验证媒体。

更新 2026-11-02 · 审核信息 2026-11-02

小白：先选模型的任务协议

从模型广场复制精确模型 ID，使用该模型快速上手中的提交示例。只有响应真正返回任务 ID 时，才进入任务查询流程。HTTP 200 只说明本次 HTTP 请求成功，不表示图片、视频或音频已生成。

已停用的通用包装

/async/* 已停用，鉴权通过后返回 HTTP 410 endpoint_deprecated；/get-async 已移除，返回 404。不要给任意路径加 /async，也不要套用旧的双层任务或 Base64 结果信封。普通同步和 SSE 请求保持原有协议。

提交与查询配对

提交协议	查询入口	成功 / 失败终态
统一视频或异步图片	`GET /v1/videos/{task_id}`	按实际适配器响应解析；常见 completed / failed
FLUX 原生 flux-3-image	`GET /flux/v1/get_result?id={task_id}`	Ready / Error
Suno v2	`GET /suno/v2/fetch/{task_id}`	data.status: SUCCESS / FAILURE
Kling	`GET /kling/v1/{category}/{kind}/{task_id}`	data.status: SUCCESS / FAILURE
Midjourney	`GET /mj/task/{task_id}/fetch`	status: SUCCESS / FAILURE

Kling 的 category、kind 和 Midjourney 模式前缀须与提交对应。不同协议的 ID、响应字段与状态大小写不能混用。查询应使用创建任务账号及相应权限的 Key。

查询与下载示例

下面只查询已创建的 FLUX 任务，不会再次发起生成：

curl --fail-with-body "$BASE_URL/flux/v1/get_result?id=$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

Pending 表示继续等待；Ready 后读取 result.sample 下载图片；Error 表示生成失败，应记录 error 并停止轮询。视频内容入口为 GET /v1/videos/{task_id}/content，成功响应是媒体字节，不能按 JSON 解析。结果链接和保存期依实际协议与存储配置，完成后及时保存。

退避、超时与计费

以 1、2、4、8 秒等间隔退避，设置最大间隔和总截止时间。连接超时可能发生在上游接受请求之后，不能自动重复提交。保存任务 ID 和请求 ID；没有任务 ID 时可按请求 ID 查消费日志。预扣和结算不等于生成成功。

专家：结果恢复与排障

GET /v1/images/generations/result?request_id=... 用于恢复图片请求的已保存链接，不是通用任务查询。processing_or_not_found 不能区分处理中、记录不存在、无权访问或无可恢复链接，不能据此无限轮询或重发。成功验收必须确认终态、结果字段和实际可读取媒体；仅有任务 ID 不算成功。

适用场景

长耗时媒体与批处理请求
避免客户端连接超时并可靠取得结果

API 协议

/v1/videos
/v1/videos/{task_id}
/flux/v1/get_result
/suno/v2/fetch/{task_id}

常见问题

还能给请求加 /async 吗？

不能，旧接口返回 410；选择该模型原生任务协议。

查询返回 200 就完成了吗？

不能只看 HTTP 状态，须确认任务成功终态并验证媒体。

超时后能重发吗？

先查已有任务和请求日志，避免创建重复收费任务。