> ## 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. # Query Task Status > - Query the current status and result of an asynchronous task - Task status flow: `pending` → `processing` → `completed` / `failed` - Optionally pass `sync_upstream=true` to proactively refresh the latest status for tasks still in progress - After task completion, result links are valid for 24 hours; please save them promptly ## `results` Field Format After a task completes (`status=completed`), `results` is an array whose **structure varies by model**. Before parsing results, check the `model` field in the response to determine the structure type. ### Common Format (Most Models) Grouped by task output type (`type`): | `type` | `results[i]` Structure | Typical Use Cases | | --------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | `image` | `{url}` | Image generation, editing, enhancement | | `video` | `{url}` | Video generation, lip-sync, video editing | | `audio` (TTS / Music) | `{url}` | Text-to-speech, music generation | | `llm` | Full OpenAI `ChatCompletion`: `{id, object:"chat.completion", created, model, choices[].message, usage}` | LLM generation (llm\_router / llm\_async) | > All `url` links are valid for 24 hours. Please save them promptly. ### Special Formats (By `model`) The `results[i]` structure for the following models **does not follow** the common format above. Callers must handle them separately based on `model`. #### Profile Creation (No Media URL Returned) | `model` | `type` | `results[i]` Structure | Notes | | -------------------------- | ------- | --------------------------- | -------------------------------------------------------------------------------------------------------- | | `kling-video-create-voice` | `video` | `{voice_id}` | Creates a reusable voice profile ID for subsequent Kling lip-sync / synthesis tasks | | `sora-2-character` | `video` | `{character_id, name}` | Extracts a character profile from a reference video for character consistency in subsequent Sora 2 tasks | | `phota-create-profile` | `image` | `{result_type, profile_id}` | Trains a person profile for use by other PHOTA models; `result_type` is always `profile` | #### Voice Cloning | `model` | `type` | `results[i]` Structure | Notes | | --------------------- | ------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `minimax-voice-clone` | `audio` | `{voice_id}`; with preview text, additionally returns `{url, content_type}` | MiniMax voice cloning: submit a reference audio to generate a reusable voice ID; if preview text is provided, the preview audio `url` is also returned | #### Speech Transcription (No Media URL Returned) | `model` | `type` | `results[i]` Structure | Notes | | ----------- | ------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | `scribe-v2` | `audio` | `{text, language_code, language_probability, words[]}` | Speech-to-text. `words[]` is a word-level timestamp array; each entry contains `text` / `start` / `end` / `type` | #### Video with Seed Value | `model` | `type` | `results[i]` Structure | Notes | | -------------------------------------- | ------- | ---------------------- | ------------------------------------------------------------ | | `seedance-2.0-text-to-video` | `video` | `{url, seed}` | Additionally returns the generation seed for reproducibility | | `seedance-2.0-fast-text-to-video` | `video` | `{url, seed}` | Same as above | | `seedance-2.0-image-to-video` | `video` | `{url, seed}` | Same as above | | `seedance-2.0-fast-image-to-video` | `video` | `{url, seed}` | Same as above | | `seedance-2.0-reference-to-video` | `video` | `{url, seed}` | Same as above | | `seedance-2.0-fast-reference-to-video` | `video` | `{url, seed}` | Same as above | The `seed` field is **always present**: it is the corresponding integer when the generation process returns a seed; if no seed is returned for this generation, it is `null`. Handle it as "field always present, value may be `null`". #### Reference Video Fast Variant Degradation Notice (`degraded_reason`) | `model` | `type` | `results[i]` Structure | Notes | | -------------------------------------- | ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `seedance-2.0-fast-reference-to-video` | `video` | `{url, degraded_reason?}` | When the requested media combination is "image + audio" or "video + audio", the fast variant has no corresponding model, so the system automatically falls back to the standard reference-video model and injects explanatory text into `results[0].degraded_reason`. Other media combinations do not include this field. | #### PBR Material (Single Task Returns Multiple Semantically Labeled Results) | `model` | `type` | `results[i]` Structure | Notes | | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `patina-pbr-maps` | `image` | `{url, content_type, result_type: "pbr_map", map_type}` | PBR map generation. `map_type` identifies the map type (e.g. `albedo` / `normal` / `roughness`, etc.) | | `patina-material` | `image` | Mixed: `{url, content_type, result_type: "texture"}` and `{url, content_type, result_type: "pbr_map", map_type}` | Outputs both tiling textures and multiple PBR maps; distinguish by `result_type` | | `patina-material-extract` | `image` | Same as `patina-material` | Extracts textures from an existing image to generate a PBR map set | #### Music Generation with Lyrics Text | `model` | `type` | `results[i]` Structure | Notes | | ------------- | ------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `lyria-3` | `audio` | `{url}`, some candidates add `{lyrics}` | 30-second music clip; `lyrics` is the generated lyrics / section structure text, returned only by some candidates and omitted when absent | | `lyria-3-pro` | `audio` | `{url}`, some candidates add `{lyrics}` | Full song (up to \~3 minutes); same as above, `lyrics` may be omitted depending on the candidate | #### Document Conversion (Result Is a ZIP Archive URL, Not a Direct Media Link) | `model` | `type` | `results[i]` Structure | Notes | | ---------- | ---------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `doc2x-v3` | `document` | `{url}` | PDF conversion result. `url` points to a downloadable ZIP archive containing the converted document files (md / tex / docx) and image assets; **unlike the direct media URLs of image/video, this URL must be extracted before use** | ### Parsing Recommendations * **Read `model` first, then parse `results`**: Different models under the same `type` may have completely different structures * **Mind the expiration for URL results**: All `url` links are valid for 24 hours; your application should download and store them immediately upon receipt * **Profile-type tasks** return `voice_id` / `character_id` / `profile_id` as long-lived resource identifiers that can be used directly in subsequent task parameters ## OpenAPI ````yaml openapi/en/get-task-detail.json GET /v1/tasks/{task_id} openapi: 3.1.0 info: title: Task Query version: '1.0' servers: - url: https://api.aihubmax.com security: - BearerAuth: [] paths: /v1/tasks/{task_id}: get: tags: - Task Management summary: Query Task Status description: > - Query the current status and result of an asynchronous task - Task status flow: `pending` → `processing` → `completed` / `failed` - Optionally pass `sync_upstream=true` to proactively refresh the latest status for tasks still in progress - After task completion, result links are valid for 24 hours; please save them promptly operationId: get-task-detail parameters: - name: task_id in: path required: true schema: type: string example: task-unified-1757165031-uyujaw3d description: Task ID, returned by the task submission endpoint - name: sync_upstream in: query required: false schema: type: boolean default: false example: true description: >- Whether to proactively refresh the task status before returning. Only takes effect for tasks that are still in progress and have an associated remote task; otherwise, the current task status is returned directly. responses: '200': description: Query successful content: application/json: schema: $ref: '#/components/schemas/TaskResponse' examples: pending: summary: Pending 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: Processing 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: Completed - Video Task 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: Completed - Image Task 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: Completed - Audio Task (TTS / Music) 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: Completed - Audio Task (STT Transcription) 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: Completed - Audio Task (Voice Clone) 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: Completed - LLM Task (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: Failed 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: Task ID example: task-unified-1757165031-uyujaw3d object: type: string description: Specific task type enum: - video.generation.task - image.generation.task - audio.generation.task - llm.generation.task example: video.generation.task type: type: string description: Task output type enum: - video - image - audio - llm example: video model: type: string description: Actual model name used example: lipsync-2 status: type: string description: | Task status **Options:** | Value | Meaning | |---|---| | `pending` | Pending | | `processing` | Processing | | `completed` | Completed | | `failed` | Failed | enum: - pending - processing - completed - failed example: pending progress: type: integer description: Task progress percentage minimum: 0 maximum: 100 example: 0 created: type: integer description: Task creation timestamp (Unix seconds) example: 1757165031 results: type: array nullable: true description: > Task result list; only populated when `status=completed`. **Structure varies by task output type (`type`):** | `type` | `results[i]` structure | Typical scenarios | |---|---|---| | `image` | `{url}`, some models include `content_type`; special tasks (e.g. PHOTA profile creation) return `{result_type, profile_id}` | Image generation, editing, enhancement | | `video` | `{url}`, some models include `content_type` / `seed`; special subtasks (Kling voice creation / Sora 2 character profile) return `{voice_id}` or `{character_id, name}` | Video generation, lip-sync | | `audio` (TTS / Music) | `{url}` | Text-to-speech, music generation | | `audio` (STT / Transcription) | `{text, language_code, language_probability, words[]}` (**no url**) | Speech transcription (e.g. Scribe V2) | | `audio` (Voice Clone) | `{voice_id}`; with preview text, additionally returns `{url, content_type}` | Voice cloning (e.g. MiniMax Voice Clone) | | `llm` | Full OpenAI `ChatCompletion`: `{id, object:"chat.completion", created, model, choices[].message, usage}` | LLM generation (llm_gateway / llm_async) | **General notes:** - Result URLs are valid for 24 hours; please save them promptly - `type=llm` results are conversation responses and do not produce URLs - Some tasks produce non-media artifacts (voice profile / character profile creation, etc.); `results` contains id-type fields instead of `url` 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: Error information; only populated when `status=failed` properties: code: type: string description: Error code example: task_failed message: type: string description: Error description example: Content policy violation type: type: string description: Error type example: task_error usage: type: object nullable: true description: Billing information properties: credits_reserved: type: integer description: Credits reserved example: 5 user_group: type: string description: Actual billing group example: default ImageResult: type: object description: >- Image result (`type=image`). Most image models only return `url`; some models (Patina family) also include `content_type`; PHOTA profile creation tasks return `{result_type, profile_id}` (non-image artifact) properties: url: type: string description: Image download URL (valid for 24 hours) example: https://example.com/output.png content_type: type: string description: MIME type; only returned by some models (e.g. Patina) example: image/png result_type: type: string description: >- Special result type marker (e.g. `profile`); only returned by PHOTA profile creation and similar non-image artifact tasks example: profile profile_id: type: string description: >- Profile ID returned by profile creation tasks (when `result_type=profile`) VideoResult: type: object description: >- Video result (`type=video`). Most video models only return `url`; some models include `content_type` (e.g. Fabric) or `seed` (e.g. Seedance 2); Kling voice creation / Sora 2 character creation subtasks return id-type fields with **no url** properties: url: type: string description: Video download URL (valid for 24 hours) example: https://example.com/output.mp4 content_type: type: string description: MIME type; only returned by some models example: video/mp4 seed: type: integer description: Generation seed; returned by models such as Seedance 2 voice_id: type: string description: >- Voice profile ID returned by Kling voice creation subtasks (no url in this case) character_id: type: string description: >- Character ID returned by Sora 2 character creation subtasks (no url in this case) name: type: string description: Character name returned by Sora 2 character creation subtasks AudioUrlResult: type: object description: >- Audio URL result (`type=audio`, TTS / music generation, e.g. Speech 2.8, Minimax Music, Gemini 3.1 Flash TTS) required: - url properties: url: type: string description: Audio download URL (valid for 24 hours) example: https://example.com/output.mp3 AudioTranscriptResult: type: object description: >- Audio transcription result (`type=audio`, STT, e.g. Scribe V2). **Does not contain url**; returns text and word-level timestamps directly properties: text: type: string description: Full transcription text example: Hello world. language_code: type: string description: Detected language code example: en language_probability: type: number description: Language detection confidence (0-1) example: 0.98 words: type: array description: >- Word-level timestamp array. Specific keys depend on the upstream ASR model (Scribe V2 typical fields: `text` / `start` / `end` / `type`, etc.) items: type: object AudioVoiceCloneResult: type: object description: >- Voice cloning result (`type=audio`, e.g., MiniMax Voice Clone). Always returns `voice_id`; if the request included preview text, additionally returns the preview audio's `url` / `content_type` required: - voice_id properties: voice_id: type: string description: >- Reusable cloned voice ID, referenced by subsequent TTS tasks (long-lived) example: Voiced689cc871778686453 url: type: string description: >- Preview audio download URL (valid for 24 hours); returned only when the request includes preview text example: https://example.com/voice-clone-preview.mp3 content_type: type: string description: Preview audio MIME type; present only when `url` is returned example: audio/mpeg LLMResult: type: object description: >- LLM result (`type=llm`). Full OpenAI `ChatCompletion` object. llm_gateway / llm_async converts the native response from each provider family (OpenAI / Anthropic / Gemini) into this structure before writing it to the task; for streaming tasks, the final result is assembled from accumulated chunks required: - id - object - created - model - choices properties: id: type: string description: ChatCompletion ID (returned by upstream or generated by gateway) example: gen-1776874579-7ojyQ9IHTeBJOuuYFclq object: type: string enum: - chat.completion example: chat.completion created: type: integer description: Creation time (Unix seconds) example: 1776874579 model: type: string description: >- Actual model identifier returned by the upstream provider (may differ from the `model` submitted in the request, as it can be the provider's full model version) 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: >- Full accumulated content. **Known limitation**: for thinking models such as `model=kimi-k2.6`, the `reasoning_content` is not accumulated into this field, which may be an empty string (the full thinking process is only visible in the SSE stream) example: 1, 2, 3 finish_reason: type: string description: >- Termination reason: `stop` / `length` / `content_filter` / `tool_calls` example: stop usage: type: object description: >- Token usage (mapped from each provider family's response; Anthropic / Gemini converted from `usageMetadata` or `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: Model fingerprint that may be returned by the OpenAI family ErrorResponse401: type: object properties: error: type: object properties: message: type: string example: Invalid API Key type: type: string example: authentication_error ErrorResponse404: type: object properties: error: type: object properties: message: type: string example: Task not found type: type: string example: not_found ErrorResponse429: type: object properties: error: type: object properties: message: type: string example: Rate limit exceeded type: type: string example: rate_limit_error ErrorResponse500: type: object properties: error: type: object properties: message: type: string example: Internal server error type: type: string example: server_error responses: Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse401' NotFound: description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse404' TooManyRequests: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse429' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse500' securitySchemes: BearerAuth: type: http scheme: bearer description: | ## All endpoints require Bearer Token authentication ## Add the following to your request headers: `Authorization: Bearer YOUR_API_KEY` ````