> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socialvision.tisyk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 异步任务通用说明

> 快速开始：异步任务通用说明

适用于视频生成、Suno 音乐、Kling 等 **非即时返回** 的接口。

## 标准流程

```text theme={null}
1. 提交任务（POST）→ 获得 task_id / task_batch_id
2. 轮询查询（GET）→ status: pending / processing / succeed / failed
3. 终态后读取 result URL 或产物列表
```

## 状态机（概念）

| 状态 | 含义 |
| - | - |
| pending / processing | 进行中，继续轮询 |
| succeed / success | 成功，读取结果字段 |
| failed / error | 失败，查看 message / error |

各平台字段名可能不同，以门户该接口 OpenAPI 响应 schema 为准。

## 轮询建议

* 间隔：3–10 秒（勿低于 1 秒高频轰炸）
* 超时：业务侧设置总超时（如 10–30 分钟）
* 幂等：同一 `task_id` 可重复查询，勿重复提交相同任务除非文档允许

## Open 格式 vs Legacy 格式

部分平台存在两套响应：

| 类型 | 任务 ID 字段示例 |
| - | - |
| Open | `taskBatchId` |
| Legacy | `data` 内 `task_id` |

文档元信息中会标注「适用协议」；勿混用轮询路径。

## 平台专题

| 平台 | 文档 |
| - | - |
| VEO / 统一视频 | [统一视频 VEO 接口文档](/reference/veo) |
| Suno | [Suno 接口文档](/reference/suno) |
| Kling | [可灵 Kling 接口文档](/reference/kling) |

## 常见错误

汇总自入门指南、[HTTP 状态码](/http-status-codes)、各平台 Quick Start / OpenAPI `x-error-playbook`，以及异步轮询侧常见现象。业务错误有时仍返回 **HTTP 200**，错误写在 JSON 的 `message` / `error` / `fail_reason` 中——勿只看状态码。

| 现象 | 可能原因 | 建议 |
| - | - | - |
| `invalid character '<' looking for beginning of value`（或响应体以 `<` 开头） | Base URL / 路径填错，返回了 HTML 登录页或官网页 | 确认网关地址与平台前缀（如 `/suno/...`、`/kling/v1/...`、`/v1/video/...`），响应须为 JSON |
| **401** | API Key 无效、过期、未传 `Authorization` | 使用 `Bearer sk-...`；在控制台确认令牌状态 |
| **403** | 无权限、令牌模型限制、分组不允许、IP 不在白名单 | 检查令牌可用模型 / 分组 / `allow_ips` |
| **400** / `invalid_request` | 参数缺失、类型错误、JSON 无法解析 | 对照该接口 OpenAPI 的 required / enum / 示例 |
| **404** / `task_not_exist` | 路径错误，或 `task_id` 不存在 / 不属于当前 Key | 核对 path；确认提交返回的 ID，勿用错字段 |
| **429** | 触发限流 | 退避重试；降低并发与轮询频率（建议 3–10s） |
| **408** / 客户端超时 | 提交或轮询 HTTP 超时过短 | 提交可适当加大 timeout；生成本身靠轮询，勿指望单次请求等出片 |
| **502 / 503 / 504** | 网关或上游暂不可用 / 超时 | 指数退避重试；高峰期降并发或换模型 |
| **HTTP 200 但 body 报错** | 业务失败写在 JSON 内 | 解析 `success` / `code` / `message` / `error`，勿仅凭 HTTP 码判断成功 |
| **模型不存在** / 无可用渠道 (`channel_not_found`) | 模型名拼写错误，或当前分组/令牌无对应渠道 | 对照控制台「支持模型」与令牌分组；必要时换分组或模型 |
| **余额 / 额度不足** | 预扣费失败 | 充值或提高令牌额度后再提交 |
| **枚举 `literal_error`** | 请求体 enum（如 Suno `mv`）不在上游允许列表 | 对照接口文档 enum / `x-error-playbook` 与渠道实测 |
| **Open / Legacy 字段混用** | 用错任务 ID 字段或轮询路径 | Open 侧常见 `taskBatchId`；Legacy 常见 `data.task_id`；提交与查询必须成对、协议一致 |
| **`task_id` 与 `clip_id` 混用**（Suno 等） | 轮询用了续写 ID，或续写用了任务 ID | 轮询用提交返回的 `task_id`；续写 / 补段用 fetch 结果中的 `clip_id` |
| **提交成功但一直 pending / processing** | 上游排队、渠道拥堵或异常 | 按建议间隔继续轮询；业务侧设总超时（如 10–30 分钟）；持续异常带任务 ID 联系运维查渠道日志 |
| **任务超时失败**（`fail_reason` 含 timed out 等） | 超过平台任务超时（常见约数十分钟量级） | 查看 `fail_reason`；失败终态通常会退还本次预扣额度；勿重复高频重提同一失败任务 |
| **终态 `failed` / `error`** | 上游生成失败、参数不合规、内容审核等 | 读 `message` / `error` / `fail_reason`；按文案改 prompt / 素材后重试 |
| **参考图 / 素材 URL 失效** | 图床临时链过期，上游拉取失败 | 换可公网访问的稳定地址，或按[图床说明](/image-host)转存后再传 |
| **图生 / 多模态任务失败** | 图片过大、非图片 MIME、格式不受支持 | 按接口限制压缩与转码后再提交 |
| **轮询路径 404 或状态字段为空** | 提交接口与查询接口不成对（如 Kling 各任务类型 path 不同） | 以门户该操作的 OpenAPI 为准，成对使用提交 + 查询 path |
| **重复提交同一任务** | 客户端超时后重试导致多扣费 / 多任务 | 同一业务请求先查已有 `task_id`；仅在文档允许时重新提交 |

更多平台专属排错见各接口 OpenAPI 的 `x-error-playbook`，以及 [HTTP 状态码及其含义](/http-status-codes)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.