task_id immediately, while an interrupted LLM request is completed by the platform and its final response is saved. All three share the same task statuses, query endpoints, and result download flow.
Use the same API Key that created the task to query it and download its results. Tasks are isolated per API Key. Two keys under the same account cannot read each other’s tasks.
Enable async tasks in the console
Enable async tasks for your account before creating async image or video tasks. If the entry is not visible in the console yet, contact AIHubMix technical support.
1. Quickstart
The full flow for async image and video tasks has three steps:2. Synchronous Calls vs. Async Tasks
A synchronous call returns the result within a single HTTP response, and the result is unavailable once the connection drops. An async task stores the result on the platform, and the
task_id can be used with the same API Key to query and download it again before the result expires. This suits long-running generation requests, and long text output that needs to be retrieved after an interruption.
3. API Overview
Base URL:
https://aihubmix.com, authenticated with a Bearer token:
/ai/v1/tasks is a read-only unified query entry point and does not provide POST /ai/v1/tasks. Images and videos are created through their respective generation endpoints. Requests that meet the LLM interruption recovery conditions are automatically recorded as llm tasks after the client is interrupted.4. Supported Models
Async task support is defined per task type, and no extra parameter is needed when calling.4.1 Async Images
4.2 Async Videos
4.3 LLM Interruption Recovery
The supported range keeps expanding, and this table is updated accordingly.
5. How to Create an Async Task
5.1 Async Images
The image endpoint returns synchronously by default. Settingasync to true makes the endpoint return a task object immediately while generation continues in the background.
async must be a boolean. When it is omitted or set to false, the image endpoint keeps its synchronous behavior.
5.2 Async Videos
The video endpoint is always asynchronous. A successful creation returns thepending or in_progress status, and switching to synchronous waiting through Prefer: wait is not supported.
5.3 Common Parameters
model, prompt, n, seconds, and size in the examples are common model parameters. The fields and values each model supports are defined by that model’s API documentation; for video models, see the video generation docs. The table below only covers the parameters shared by all async tasks.
Image tasks can only use webhooks when
async: true. When webhook_events_filter is omitted, the platform pushes all three final statuses: completed, failed, and cancelled. When it is provided, it must be used together with webhook_url, and it cannot be empty or contain duplicates.6. How LLM Interruption Recovery Works
LLM interruption recovery is used to retrieve the final response after the client disconnects. It reuses the existing way of making LLM requests, keeps streaming behavior and response formats unchanged, requires no additional creation endpoint, and does not return atask_id in advance.
6.1 Conditions
All of the following conditions must be met at the same time:
Supported endpoints:
No extra field is needed when calling. For the supported range, see 4.3 LLM Interruption Recovery. For models not listed in that table, run one low-cost request to verify interruption recovery before going live; the verification request is still billed normally. If any condition is not met, the request still runs normally, and no
llm task is created after a client interruption.6.2 Execution Flow After an Interruption
6.3 Locating the Matching Interrupted Request
LLM responses include theX-Aihubmix-Request-Id response header. The client should save this value as soon as the response headers arrive. After an interruption, the request ID can be used to find the matching task in the async task list in the AIHubMix console.
The public task API currently does not support filtering by request ID. If the request ID was not saved, the only option is to use the same API Key that created the request and search by model and creation time:
7. Task Object and Statuses
All tasks use a unified response structure:
Result fields inside
output:
7.1 Status Reference
Poll every 15 seconds until the status becomes
completed, failed, or cancelled.
A
failed or cancelled task may still contain results that were already generated. When checking whether results exist, also check whether output is empty in addition to the status.8. How to Query Tasks
8.1 Get Task Details
8.2 List Tasks
If the creation response is lost, or historical tasks need to be reviewed in bulk, the list endpoint can recover thetask_id:
Example response:
Request the next page:
9. How to Get Task Results
9.1 Single-Output Tasks
Whenoutput contains only one file, it can be accessed directly:
output[0].content_url can also be used directly. The Content-Type of the download response matches output[0].content_type.
9.2 Multi-Output Tasks
Whenoutput contains several files, the matching result_id must be specified:
result_id is not specified for a multi-output task, the endpoint returns 400 result_id_required.
9.3 LLM Response Tasks
Once the LLM interruption recovery conditions are met and the response is saved, the task hasobject set to llm and the output item has type set to response. The content type can be:
application/json: a regular JSON responsetext/event-stream: a saved SSE streaming response
output[0].truncated of the task details. A value of true means the saved response was truncated because of a size limit. GET /ai/v1/tasks/{task_id}/content returns the raw JSON or SSE content without wrapping it in a truncated field, so query the task details before reading the content.
10. How to Use Webhooks
Task-level webhooks can currently be submitted when creating an async task. To have AIHubMix notify you after a task finishes, passwebhook_url and the optional webhook_events_filter in the async image or video request body:
10.1 Callback Request
AIHubMix sends aPOST request to the callback URL:
The URLs in
results still require the API Key that created the task.
10.2 Retries and Deduplication
The platform attempts delivery at least once, so the same event may be sent more than once:- HTTP
2xxmeans the callback was received successfully. - HTTP
5xx, network errors, or timeouts trigger a retry. - HTTP
3xxand4xxare not retried. - Up to 6 deliveries, with retry intervals of 1, 4, 16, 64, and 256 seconds.
event_id. When the same event_id arrives again, skip the business logic and return 2xx directly.
11. Error Responses and Error Codes
Error responses use a unified structure:12. Full Example
The full flow of creating a video task, polling its status, and downloading all results:FAQ
How often should the task status be queried? Poll every 15 seconds and avoid high-frequency polling. Even when using webhooks, keep low-frequency polling as a backup. How can a task be recovered after the creation response is lost? Use the same API Key that created the task to requestGET /ai/v1/tasks, and narrow the range with object, model, and status.
Why can another API Key under the same account not find the task?
Tasks are isolated per API Key. Query, download, and list requests must all use the same key that created the task.
Why is output not an empty array when the task failed?
Some models may have produced deliverable results before the task failed or was cancelled overall. As long as content_url or b64_json is present in output, the result can be retrieved in the corresponding way.
What should be done when a webhook is not received?
Confirm that the callback URL is publicly reachable, uses HTTPS, and returns 2xx within 10 seconds. The final status can always be queried through GET /ai/v1/tasks/{task_id}, whether or not webhooks are used.
Does LLM interruption recovery require changes to existing code?
No. The request method, streaming behavior, and response format stay the same. Save the X-Aihubmix-Request-Id response header so the matching task can be located precisely in the console after an interruption.
Last updated: 2026-07-28