> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmax.com/llms.txt > Use this file to discover all available pages before exploring further. # 查询任务状态 > - 查询异步任务的当前状态和结果 - 任务状态流转：`pending` → `processing` → `completed` / `failed` - 可选传入 `sync_upstream=true`，对仍在执行中的任务先主动刷新一次最新状态 - 任务完成后，结果链接有效期为24小时，请尽快保存 ## `results` 字段格式说明 任务完成（`status=completed`）后，`results` 是一个数组，**结构按模型不同而异**。解析结果前请先根据响应中的 `model` 字段判定结构类型。 ### 通用格式（大多数模型） 按任务输出类型（`type`）分组： | `type` | `results[i]` 结构 | 典型场景 | | ----------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------- | | `image` | `{url}` | 图片生成、编辑、增强 | | `video` | `{url}` | 视频生成、对口型、视频编辑 | | `audio`（TTS / 音乐） | `{url}` | 语音合成、音乐生成 | | `llm` | 完整 OpenAI `ChatCompletion`：`{id, object:"chat.completion", created, model, choices[].message, usage}` | LLM 生成（llm\_router / llm\_async） | > `url` 有效期均为 24 小时，请尽快保存。 ### 特殊格式（按 `model` 区分） 以下模型的 `results[i]` 结构**不遵循**上表通用格式。调用方必须按 `model` 单独处理。 #### 档案创建类（不返回媒体 URL） | `model` | `type` | `results[i]` 结构 | 说明 | | -------------------------- | ------- | --------------------------- | ------------------------------------------------- | | `kling-video-create-voice` | `video` | `{voice_id}` | 创建可复用的语音档案 ID，供后续 Kling 对口型 / 合成任务引用 | | `sora-2-character` | `video` | `{character_id, name}` | 从参考视频提取角色档案，供后续 Sora 2 任务实现角色一致性 | | `phota-create-profile` | `image` | `{result_type, profile_id}` | 训练人物档案，供其他 PHOTA 模型引用；`result_type` 固定为 `profile` | #### 声音克隆类 | `model` | `type` | `results[i]` 结构 | 说明 | | --------------------- | ------- | ------------------------------------------- | ------------------------------------------------------- | | `minimax-voice-clone` | `audio` | `{voice_id}`，带预览文本时附加 `{url, content_type}` | MiniMax 声音克隆：提交参考音频生成可复用的声音 ID；若请求带了预览文本，额外返回预览音频 `url` | #### 语音转写类（不返回媒体 URL） | `model` | `type` | `results[i]` 结构 | 说明 | | ----------- | ------- | ------------------------------------------------------ | -------------------------------------------------------------- | | `scribe-v2` | `audio` | `{text, language_code, language_probability, words[]}` | 语音转文本。`words[]` 为字级时间戳数组，每项含 `text` / `start` / `end` / `type` | #### 视频带种子值 | `model` | `type` | `results[i]` 结构 | 说明 | | -------------------------------------- | ------- | --------------- | ------------- | | `seedance-2.0-text-to-video` | `video` | `{url, seed}` | 额外返回生成种子，用于复现 | | `seedance-2.0-fast-text-to-video` | `video` | `{url, seed}` | 同上 | | `seedance-2.0-image-to-video` | `video` | `{url, seed}` | 同上 | | `seedance-2.0-fast-image-to-video` | `video` | `{url, seed}` | 同上 | | `seedance-2.0-reference-to-video` | `video` | `{url, seed}` | 同上 | | `seedance-2.0-fast-reference-to-video` | `video` | `{url, seed}` | 同上 | `seed` 字段**始终存在**：当生成过程回传了种子时为对应整数；若本次生成未回传种子，则为 `null`。请按「字段始终存在、值可能为 `null`」处理。 #### 参考视频快速版降级提示（`degraded_reason`） | `model` | `type` | `results[i]` 结构 | 说明 | | -------------------------------------- | ------- | ------------------------- | --------------------------------------------------------------------------------------------------- | | `seedance-2.0-fast-reference-to-video` | `video` | `{url, degraded_reason?}` | 当请求的媒体组合为「图+音」或「视频+音」时，快速版无对应模型，系统自动降级到标准参考视频模型，并在 `results[0].degraded_reason` 注入说明文本。其余媒体组合不含该字段。 | #### PBR 材质类（单任务返回多个带语义标签的结果） | `model` | `type` | `results[i]` 结构 | 说明 | | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | | `patina-pbr-maps` | `image` | `{url, content_type, result_type: "pbr_map", map_type}` | PBR 贴图生成。`map_type` 标识贴图类型（如 `albedo` / `normal` / `roughness` 等） | | `patina-material` | `image` | 混合两种：`{url, content_type, result_type: "texture"}` 与 `{url, content_type, result_type: "pbr_map", map_type}` | 同时输出平铺纹理和多张 PBR 贴图；按 `result_type` 区分 | | `patina-material-extract` | `image` | 同 `patina-material` | 从现有图提取纹理生成 PBR 贴图组 | #### 音乐生成带歌词文本 | `model` | `type` | `results[i]` 结构 | 说明 | | ------------- | ------- | ------------------------- | -------------------------------------------------- | | `lyria-3` | `audio` | `{url}`，部分候选附加 `{lyrics}` | 30 秒音乐片段；`lyrics` 为生成的歌词 / 段落结构文本，仅部分候选返回，缺省时不含该字段 | | `lyria-3-pro` | `audio` | `{url}`，部分候选附加 `{lyrics}` | 完整歌曲（最长约 3 分钟）；同上，`lyrics` 按候选不同可能缺省 | #### 文档转换类（结果为 ZIP 压缩包 URL，非媒体直链） | `model` | `type` | `results[i]` 结构 | 说明 | | ---------- | ---------- | --------------- | ------------------------------------------------------------------------------------------------------------ | | `doc2x-v3` | `document` | `{url}` | PDF 转换结果。`url` 指向一个可下载的 ZIP 压缩包，内含转换后的文档文件（md / tex / docx）及图片资源；**与 image/video 的直接媒体 URL 不同，此 URL 需解压后使用** | ### 解析建议 * **先读 `model`，再解析 `results`**：同一 `type` 下不同 `model` 的结构可能完全不同 * **URL 类结果注意过期**：所有 `url` 有效期 24 小时，业务侧应在收到结果后立即下载转存 * **档案类任务**返回的 `voice_id` / `character_id` / `profile_id` 是长期有效的资源标识，可直接用于后续任务参数 ## OpenAPI ````yaml openapi/zh/get-task-detail.json GET /v1/tasks/{task_id} openapi: 3.1.0 info: title: 任务查询 version: '1.0' servers: - url: https://api.aihubmax.com security: - BearerAuth: [] paths: /v1/tasks/{task_id}: get: tags: - Task Management summary: 查询任务状态 description: | - 查询异步任务的当前状态和结果 - 任务状态流转：`pending` → `processing` → `completed` / `failed` - 可选传入 `sync_upstream=true`，对仍在执行中的任务先主动刷新一次最新状态 - 任务完成后，结果链接有效期为24小时，请尽快保存 operationId: get-task-detail parameters: - name: task_id in: path required: true schema: type: string example: task-unified-1757165031-uyujaw3d description: 任务ID，由提交任务接口返回 - name: sync_upstream in: query required: false schema: type: boolean default: false example: true description: 是否在返回前主动刷新一次任务状态。仅对仍在执行且已有关联远端任务的记录生效；否则直接返回当前任务状态。 responses: '200': description: 查询成功 content: application/json: schema: $ref: '#/components/schemas/TaskResponse' examples: pending: summary: 等待处理 value: id: task-unified-1757165031-uyujaw3d object: video.generation.task type: video model: lipsync-2 status: pending progress: 0 created: 1757165031 results: null error: null usage: credits_reserved: 5 user_group: default processing: summary: 处理中 value: id: task-unified-1757165031-uyujaw3d object: video.generation.task type: video model: lipsync-2 status: processing progress: 50 created: 1757165031 results: null error: null usage: credits_reserved: 5 user_group: default completed_video: summary: 已完成 · 视频任务 value: id: task-unified-1757165031-uyujaw3d object: video.generation.task type: video model: lipsync-2 status: completed progress: 100 created: 1757165031 results: - url: https://example.com/output-video.mp4 content_type: video/mp4 error: null usage: credits_reserved: 5 user_group: default completed_image: summary: 已完成 · 图片任务 value: id: task-unified-1776800000-abcd1234 object: image.generation.task type: image model: gemini-3.1-flash-image-preview status: completed progress: 100 created: 1776800000 results: - url: https://example.com/output-image.png error: null usage: credits_reserved: 3 user_group: default completed_audio_tts: summary: 已完成 · 音频任务（TTS / 音乐） value: id: task-unified-1776810000-efgh5678 object: audio.generation.task type: audio model: speech-2.8 status: completed progress: 100 created: 1776810000 results: - url: https://example.com/output-audio.mp3 error: null usage: credits_reserved: 2 user_group: default completed_audio_stt: summary: 已完成 · 音频任务（STT 转写） value: id: task-unified-1776820000-ijkl9012 object: audio.generation.task type: audio model: scribe-v2 status: completed progress: 100 created: 1776820000 results: - text: Hello world. language_code: en language_probability: 0.98 words: - text: Hello start: 0 end: 0.42 type: word - text: world start: 0.48 end: 0.9 type: word error: null usage: credits_reserved: 1 user_group: default completed_audio_voice_clone: summary: 已完成 · 音频任务（声音克隆） value: id: task-unified-1778686432-pf0a0igf object: audio.generation.task type: audio model: minimax-voice-clone status: completed progress: 100 created: 1778686432 results: - voice_id: Voiced689cc871778686453 url: https://example.com/voice-clone-preview.mp3 content_type: audio/mpeg error: null usage: credits_reserved: 750000 user_group: default completed_llm: summary: 已完成 · LLM 任务（ChatCompletion） value: id: task-llm-1776874565-yq3szvcu object: llm.generation.task type: llm model: claude-opus-4-7 status: completed progress: 100 created: 1776874565 results: - id: gen-1776874579-7ojyQ9IHTeBJOuuYFclq object: chat.completion created: 1776874579 model: anthropic/claude-4.7-opus-20260416 choices: - index: 0 message: role: assistant content: 1, 2, 3 finish_reason: stop usage: prompt_tokens: 9 completion_tokens: 12 total_tokens: 21 error: null usage: credits_reserved: 10 user_group: default failed: summary: 已失败 value: id: task-unified-1757165031-uyujaw3d object: video.generation.task type: video model: lipsync-2 status: failed progress: 0 created: 1757165031 results: null error: code: task_failed message: Content policy violation type: task_error usage: credits_reserved: 5 user_group: default '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: schemas: TaskResponse: type: object properties: id: type: string description: 任务ID example: task-unified-1757165031-uyujaw3d object: type: string description: 任务的具体类型 enum: - video.generation.task - image.generation.task - audio.generation.task - llm.generation.task example: video.generation.task type: type: string description: 任务的输出类型 enum: - video - image - audio - llm example: video model: type: string description: 实际使用的模型名称 example: lipsync-2 status: type: string description: | 任务状态 **可选值：** | 值 | 含义 | |---|---| | `pending` | 等待处理 | | `processing` | 处理中 | | `completed` | 已完成 | | `failed` | 已失败 | enum: - pending - processing - completed - failed example: pending progress: type: integer description: 任务进度百分比 minimum: 0 maximum: 100 example: 0 created: type: integer description: 任务创建时间戳（Unix 秒） example: 1757165031 results: type: array nullable: true description: > 任务结果列表，仅在 `status=completed` 时有值。 **结构按任务输出类型（`type`）不同：** | `type` | `results[i]` 结构 | 典型场景 | |---|---|---| | `image` | `{url}`，部分模型附带 `content_type`；特殊任务（如 PHOTA 创建档案）为 `{result_type, profile_id}` | 图片生成、编辑、增强 | | `video` | `{url}`，部分模型附带 `content_type` / `seed`；特殊子任务（Kling 创建语音 / Sora 2 角色档案）为 `{voice_id}` 或 `{character_id, name}` | 视频生成、对口型 | | `audio`（TTS / 音乐） | `{url}` | 语音合成、音乐生成 | | `audio`（STT / 转写） | `{text, language_code, language_probability, words[]}`（**不含 url**） | 语音转写（如 Scribe V2） | | `audio`（声音克隆） | `{voice_id}`，带预览文本时附加 `{url, content_type}` | 声音克隆（如 MiniMax Voice Clone） | | `llm` | 完整 OpenAI `ChatCompletion`：`{id, object:"chat.completion", created, model, choices[].message, usage}` | LLM 生成（llm_gateway / llm_async） | **通用说明：** - 结果中的 URL 有效期为 24 小时，请尽快保存 - `type=llm` 的结果是对话响应，不产生 URL - 部分任务是"非媒体产物"（创建语音档案 / 角色档案等），`results` 不含 `url` 而是 id 类字段 items: oneOf: - $ref: '#/components/schemas/ImageResult' - $ref: '#/components/schemas/VideoResult' - $ref: '#/components/schemas/AudioUrlResult' - $ref: '#/components/schemas/AudioTranscriptResult' - $ref: '#/components/schemas/AudioVoiceCloneResult' - $ref: '#/components/schemas/LLMResult' error: type: object nullable: true description: 错误信息，仅在 `status=failed` 时有值 properties: code: type: string description: 错误码 example: task_failed message: type: string description: 错误描述 example: Content policy violation type: type: string description: 错误类型 example: task_error usage: type: object nullable: true description: 计费信息 properties: credits_reserved: type: integer description: 预扣额度 example: 5 user_group: type: string description: 实际计费分组 example: default ImageResult: type: object description: >- 图片结果（`type=image`）。多数图片模型只返回 `url`；少数模型（Patina 家族）会附带 `content_type`；PHOTA 创建档案类任务返回 `{result_type, profile_id}`（非图片产物） properties: url: type: string description: 图片下载 URL（有效期 24 小时） example: https://example.com/output.png content_type: type: string description: MIME 类型，仅部分模型（如 Patina）返回 example: image/png result_type: type: string description: 特殊结果类型标记（如 `profile`），仅 PHOTA 创建档案等非图片产物任务返回 example: profile profile_id: type: string description: 创建档案类任务返回的档案 ID（当 `result_type=profile` 时） VideoResult: type: object description: >- 视频结果（`type=video`）。多数视频模型只返回 `url`；部分模型附带 `content_type`（如 Fabric）或 `seed`（如 Seedance 2）；Kling 创建语音 / Sora 2 创建角色等子任务返回 id 类字段，**没有 url** properties: url: type: string description: 视频下载 URL（有效期 24 小时） example: https://example.com/output.mp4 content_type: type: string description: MIME 类型，仅部分模型返回 example: video/mp4 seed: type: integer description: 生成种子，Seedance 2 等模型会回传 voice_id: type: string description: Kling 创建语音子任务返回的语音档案 ID（此时无 url） character_id: type: string description: Sora 2 创建角色子任务返回的角色 ID（此时无 url） name: type: string description: Sora 2 创建角色子任务返回的角色名 AudioUrlResult: type: object description: >- 音频 URL 结果（`type=audio`，TTS / 音乐生成，如 Speech 2.8、Minimax Music、Gemini 3.1 Flash TTS） required: - url properties: url: type: string description: 音频下载 URL（有效期 24 小时） example: https://example.com/output.mp3 AudioTranscriptResult: type: object description: 音频转写结果（`type=audio`，STT，如 Scribe V2）。**不含 url**，直接返回文本及字级时间戳 properties: text: type: string description: 完整转写文本 example: Hello world. language_code: type: string description: 检测到的语言代码 example: en language_probability: type: number description: 语言识别置信度（0-1） example: 0.98 words: type: array description: >- 字级时间戳数组。具体键由上游 ASR 模型决定（Scribe V2 典型字段：`text` / `start` / `end` / `type` 等） items: type: object AudioVoiceCloneResult: type: object description: >- 声音克隆结果（`type=audio`，如 MiniMax Voice Clone）。始终返回 `voice_id`；若请求带了预览文本，附加预览音频的 `url` / `content_type` required: - voice_id properties: voice_id: type: string description: 克隆生成的可复用声音 ID，供后续 TTS 任务引用（长期有效） example: Voiced689cc871778686453 url: type: string description: 预览音频下载 URL（有效期 24 小时），仅在请求带预览文本时返回 example: https://example.com/voice-clone-preview.mp3 content_type: type: string description: 预览音频 MIME 类型，仅在返回 `url` 时存在 example: audio/mpeg LLMResult: type: object description: >- LLM 结果（`type=llm`）。完整 OpenAI `ChatCompletion` 对象。llm_gateway / llm_async 会把家族原生响应（OpenAI / Anthropic / Gemini）统一转成该结构后写入 task；流式任务的最终结果由 chunks 累积合成 required: - id - object - created - model - choices properties: id: type: string description: ChatCompletion ID（由上游返回或网关生成） example: gen-1776874579-7ojyQ9IHTeBJOuuYFclq object: type: string enum: - chat.completion example: chat.completion created: type: integer description: 创建时间（Unix 秒） example: 1776874579 model: type: string description: 上游返回的实际模型标识（可能是 provider 侧的完整型号，与提交时的 `model` 不完全相同） example: anthropic/claude-4.7-opus-20260416 choices: type: array items: type: object properties: index: type: integer example: 0 message: type: object properties: role: type: string example: assistant content: type: string description: >- 累积后的完整正文。**已知限制**：`model=kimi-k2.6` 等 thinking 模型的 `reasoning_content` 不会累积进来，此字段可能为空串（完整思考过程仅在 SSE 流中可见） example: 1, 2, 3 finish_reason: type: string description: 终止原因：`stop` / `length` / `content_filter` / `tool_calls` example: stop usage: type: object description: >- Token 用量（由各家族响应映射，Anthropic / Gemini 从 `usageMetadata` 或 `message_delta.usage` 转来） properties: prompt_tokens: type: integer example: 9 completion_tokens: type: integer example: 12 total_tokens: type: integer example: 21 system_fingerprint: type: string description: OpenAI 家族可能返回的模型指纹 ErrorResponse401: type: object properties: error: type: object properties: message: type: string example: API密钥无效 type: type: string example: authentication_error ErrorResponse404: type: object properties: error: type: object properties: message: type: string example: 任务不存在 type: type: string example: not_found ErrorResponse429: type: object properties: error: type: object properties: message: type: string example: 请求频率超限 type: type: string example: rate_limit_error ErrorResponse500: type: object properties: error: type: object properties: message: type: string example: 服务器内部错误 type: type: string example: server_error responses: Unauthorized: description: 未授权 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse401' NotFound: description: 任务不存在 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse404' TooManyRequests: description: 请求频率超限 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse429' InternalServerError: description: 服务器内部错误 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse500' securitySchemes: BearerAuth: type: http scheme: bearer description: | ## 所有接口均需要使用Bearer Token进行认证 ## 使用时在请求头中添加： `Authorization: Bearer YOUR_API_KEY` ````