Skip to main content
Requests such as video generation and batch image generation usually take longer than a single HTTP connection can reasonably wait. For long text generation, any response already produced is lost once the client disconnects. Async Tasks bring these three scenarios into a single task object: image and video requests create a task through the generation endpoints and return a 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.
When async tasks are not enabled, media task creation requests return 403 async_not_enabled. LLM requests do not fail because of this, but the final response cannot be retrieved after a client interruption.

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. Setting async 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 the pending 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 a task_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

LLM requests that complete normally and are returned to the client successfully do not create a task and do not appear in the task list. An interrupted request appears in the list after its final response has been saved, so it may be temporarily unavailable while processing is still under way.

6.3 Locating the Matching Interrupted Request

LLM responses include the X-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:
When one API Key sends several concurrent requests to the same model, model and creation time alone cannot guarantee an exact match. For reliable recovery, save X-Aihubmix-Request-Id and look the task up in the console. If the response headers were never received, avoid treating the most recent task in the list as the one from this request.
LLM interruption recovery tasks currently do not send webhooks, so query the results through the task list. A client interruption does not stop the platform from continuing to process the request, and the call is still billed under the rules of the original LLM endpoint.

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

This endpoint returns the latest task information at query time. Querying does not change the task; the task status is updated automatically by the platform.

8.2 List Tasks

If the creation response is lost, or historical tasks need to be reviewed in bulk, the list endpoint can recover the task_id:
Example response:
Request the next page:

9. How to Get Task Results

9.1 Single-Output Tasks

When output 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

When output contains several files, the matching result_id must be specified:
If 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 has object set to llm and the output item has type set to response. The content type can be:
  • application/json: a regular JSON response
  • text/event-stream: a saved SSE streaming response
The truncation flag is in 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.
Results can expire, and a download count limit may apply. Save them before expires_at. An expired result returns 410 artifact_expired, and exceeding the download limit returns 429 too_many_downloads.

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, pass webhook_url and the optional webhook_events_filter in the async image or video request body:
The callback URL must use HTTPS and must not point to localhost, private networks, or other restricted addresses.

10.1 Callback Request

AIHubMix sends a POST 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 2xx means the callback was received successfully.
  • HTTP 5xx, network errors, or timeouts trigger a retry.
  • HTTP 3xx and 4xx are not retried.
  • Up to 6 deliveries, with retry intervals of 1, 4, 16, 64, and 256 seconds.
The receiver should store event_id. When the same event_id arrives again, skip the business logic and return 2xx directly.
Task-level webhooks currently do not provide configurable standalone signing credentials. After receiving a notification, use the API Key that created the task to request GET /ai/v1/tasks/{task_id} and treat the query result as authoritative.

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 request GET /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