Async Tasks - AIHubMix

AIHubMix provides three groups of task endpoints: /ai/v1/images for images, /ai/v1/videos for videos, and /ai/v1/tasks for unified task records.

Image generation is synchronous by default and runs asynchronously when async: true is provided.
Video generation is always asynchronous.
Image and video detail endpoints return the latest status of media tasks.
/ai/v1/tasks provides a unified read-only view of image, video, and LLM tasks.

When a Doubao Seedance video needs real-person assets, complete personal verification and asset preparation using the Doubao Real-Person Assets Guide before creating the video task.

Video tutorial: Async Tasks

Learn how async tasks work and follow a complete async image generation workflow.

Enable async tasks in the console

Before using the /ai/v1 media task endpoints, enable async tasks for the current account.

When async tasks are not enabled, image and video task creation requests return 403 async_not_enabled.

Quickstart

The following example uses wan2.6-t2v to create a video. This model accepts duration and size; valid fields vary by model.

# 1. Create a video task and save the id from the response
curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A cat playing jazz on a piano, warm lighting, cinematic shot",
    "duration": 5,
    "size": "1280x720"
  }'

# 2. Query media details every 15 seconds
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 3. Download the video after the status becomes completed
curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

Which API Group Should You Use?

Use case	Method	Path	Behavior
Generate images	POST	`/ai/v1/images/generations`	Synchronous by default; pass `async: true` for asynchronous execution
Get image details	GET	`/ai/v1/images/{id}`	Returns image task status; querying an active task may update its status
List image tasks	GET	`/ai/v1/images`	Returns snapshots of image tasks
Download a specific image	GET	`/ai/v1/images/{id}/content/{result_id}`	Downloads a specific result from a multi-image task
Create a video	POST	`/ai/v1/videos`	Always asynchronous
Get video details	GET	`/ai/v1/videos/{id}`	Returns video task status; querying an active task may update its status
List video tasks	GET	`/ai/v1/videos`	Returns snapshots of video tasks
Download a video	GET	`/ai/v1/videos/{id}/content`	Downloads the primary video result of a task
List async media models	GET	`/api/v1/models?type={type}&schema_checked=true`	Returns text-to-image or text-to-video models with request Schemas
Get a model request schema	GET	`/call/schema/models/{model}/endpoints`	Returns text-to-image or text-to-video endpoints and their JSON Schemas
List unified tasks	GET	`/ai/v1/tasks`	Read-only query for image, video, and LLM tasks
Get unified task details	GET	`/ai/v1/tasks/{id}`	Returns a read-only task snapshot at query time
Get a unified task result	GET	`/ai/v1/tasks/{id}/content`	Downloads a single artifact or reads an archived LLM response
Get a specific unified task result	GET	`/ai/v1/tasks/{id}/content/{result_id}`	Downloads a specific result from a multi-artifact task

The base URL is https://aihubmix.com. Authenticate with a Bearer token:

Authorization: Bearer $AIHUBMIX_API_KEY

The model list and model Schema endpoints are public discovery endpoints and do not require a Bearer Token. All other endpoints require authentication.

/ai/v1/tasks does not provide a creation endpoint. Images and videos must be created through their respective media generation endpoints. LLM recovery tasks are saved automatically by the platform after a client interruption.

Media Endpoints and Unified Task Endpoints

Media detail endpoints and unified task endpoints return the same top-level task fields, but their output items and query behavior differ:

Comparison	Media details `/images/{id}`, `/videos/{id}`	Unified task details `/tasks/{id}`
Task types	Image or video	Image, video, or LLM
Query behavior	Querying an active task may update its status	Returns a read-only task snapshot at query time
Media output fields	`index`, `type`, `content_url`, `b64_json`	`index`, `result_id`, `type`, `content_type`, `content_url`
LLM output fields	Not applicable	`index`, `type=response`, `content_type`, `content_url`, `truncated`
Access scope	Corresponding media tasks created by the current account	Tasks created with the current Bearer token

Use the image or video detail endpoint to poll media generation status. Use /ai/v1/tasks to filter tasks across types, read result metadata, or recover LLM responses.

How Do You Discover Async Media Models and Get Their Schemas?

The discovery flow has two steps. First, retrieve text-to-image or text-to-video models that support the async APIs from the public model catalog. Then use a model’s model_id to retrieve the request Schema for its endpoints.

List Models That Support the Async APIs

The model catalog uses the same data source as Playground. Use type=image_generation for text-to-image models and type=video for text-to-video models. Adding schema_checked=true limits the list to models with a published and reviewed request Schema.

# Text-to-image models
curl "https://aihubmix.com/api/v1/models?type=image_generation&schema_checked=true&sort_by=order"

# Text-to-video models
curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order"

Both requests use the same endpoint. The type filter currently accepts one value, so request each model type separately. The response has the shape {success, message, data}. The following fields in data are relevant to async media integrations.

Field	Description
`data[].model_id`	Model ID used in generation requests and subsequent Schema requests
`data[].model_name`	Model display name
`data[].types`	Comma-separated model types; a model may include both `image_generation` and `llm`
`data[].input_modalities`	Comma-separated input modalities
`data[].schema_checked`	`true` when the request Schema has been published and reviewed

{
  "success": true,
  "message": "",
  "data": [
    {
      "model_id": "qwen-image-2.0",
      "model_name": "Qwen Image 2.0",
      "types": "image_generation",
      "input_modalities": "text,image",
      "schema_checked": true
    }
  ]
}

Get the Request Schema for One Model

Supported fields, enumerations, and numeric ranges can vary by model. Before submitting an image or video request, use the public endpoint below to retrieve the available endpoints and request JSON Schemas for the selected model.

# Text-to-image model
curl "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints"

# Text-to-video model
curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints"

The response has a modality of image or video. Each item in the endpoints array describes one available calling protocol.

Field	Description
`default_endpoint`	Default endpoint identifier for the model
`endpoints[].endpoint`	Endpoint identifier
`endpoints[].method`	HTTP method, such as `POST`
`endpoints[].path`	Request path
`endpoints[].content_types`	Content types accepted by the endpoint
`endpoints[].lifecycle`	Sync or async mode, polling path, and status values
`endpoints[].request.schema`	Complete request JSON Schema for this model and endpoint, including required fields and value constraints

A model may return both /ai/v1 endpoints and OpenAI-compatible /v1 endpoints. OpenAI-compatible endpoints may not yet support the latest models, so prefer the /ai/v1 endpoints. For async task APIs, select the item whose path is /ai/v1/images/generations or /ai/v1/videos, then use its request.schema. Do not depend on the position of an item in the endpoints array. The following commands extract the request Schema for each async task endpoint.

# Text-to-image
curl -s "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/images/generations") | .request.schema'

# Text-to-video
curl -s "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

The endpoint returns 404 model_not_found when the model does not exist or has no discoverable endpoints. It returns 500 endpoints_unavailable when endpoint data is temporarily unavailable.

Which Models and Fields Are Supported?

The image and video protocols define standard fields across models, but each model narrows the supported fields, enumerations, and numeric ranges based on its capabilities. Before making a request, retrieve the model’s current constraints from the model Schema endpoint. For example:

wan2.6-t2v supports duration, size, and seed. It does not accept resolution, aspect_ratio, frame_images, input_references, or generate_audio.
qwen-image-2.0 supports n, size, seed, negative_prompt, image, and images. It does not accept aspect_ratio or mask.

The standard field set does not mean that every model supports every field. Passing a field unsupported by the selected model returns a parameter error.

Models for LLM Interruption Recovery

The following models are currently supported:

gpt-5.6-sol
gpt-5.5-pro
gpt-5.4-pro
gpt-5.2-pro
claude-fable-5
claude-opus-5

The supported range may change. Refer to the list on this page for the current range. The current account must also have async tasks enabled to use interruption recovery. If either condition is not met, the original LLM request still runs normally, but no recovery task is saved after the client disconnects.

How Do You Create Image Tasks?

Synchronous Images

When async is omitted or set to false, the endpoint waits for generation to finish and returns a task object:

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

Synchronous image tasks also save a task record. If the client connection is interrupted or the creation response is lost, use GET /ai/v1/images to find the corresponding task.

Asynchronous Images

When async is set to the Boolean value true, the endpoint returns a task object immediately and generation continues in the background:

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 2,
    "size": "1024x1024",
    "async": true
  }'

Use GET /ai/v1/images/{id} to query an asynchronous image task. After completion, request the content_url from each output item directly. The URL already contains the corresponding image result_id.

async in an image request must be a Boolean. webhook_url and webhook_events_filter can only be used with async: true.

Standard Image Fields

Field	Type	Required	Description
`model`	string	Yes	Model name
`prompt`	string	Yes	Image description; must not be empty
`n`	integer/null	No	Number of images, minimum `1`, default `1`
`size`	string/null	No	`{width}x{height}`, for example `1024x1024`
`aspect_ratio`	string/null	No	Aspect ratio; mutually exclusive with `size`
`seed`	integer/null	No	Random seed
`negative_prompt`	string/null	No	Negative prompt
`image`	string/object	No	One input image as a URL, Data URI, Base64 value, or `{url}` object
`images`	array/null	No	Multiple input images
`mask`	string/object	No	Image-editing mask
`output_format`	string/null	No	`png`, `jpeg`, or `webp`; default `png`
`response_format`	string/null	No	`url` or `b64_json`; default `url`
`async`	boolean	No	Set to `true` for asynchronous execution
`webhook_url`	string	No	HTTPS callback URL, up to 512 characters
`webhook_events_filter`	string[]	No	A non-empty subset of `completed`, `failed`, and `cancelled`
`extra`	object/null	No	Model-specific extension parameters

How Do You Create Video Tasks?

Video requests are always asynchronous and cannot be changed to synchronous waiting with Prefer: wait. The standard protocol uses the integer field duration for the number of seconds:

curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "Ocean waves crashing on rocky cliffs at sunset",
    "duration": 5,
    "size": "1280x720"
  }'

Standard Video Fields

Field	Type	Required	Description
`model`	string	Yes	Model name
`prompt`	string	Yes	Video description; must not be empty
`duration`	integer/null	No	Video length in seconds; the range depends on the model
`aspect_ratio`	string/null	No	Aspect ratio; protocol default `16:9`
`resolution`	string/null	No	`480p`, `720p`, `1080p`, `1K`, `2K`, or `4K`
`size`	string/null	No	`{width}x{height}`; can replace `resolution` and `aspect_ratio`
`seed`	integer/null	No	Random seed
`input_references`	array/null	No	Image, video, or audio reference assets
`frame_images`	array/null	No	First-frame or last-frame images
`generate_audio`	boolean/null	No	Whether to generate an audio track
`webhook_url`	string	No	HTTPS callback URL, up to 512 characters
`webhook_events_filter`	string[]	No	A non-empty subset of `completed`, `failed`, and `cancelled`
`extra`	object/null	No	Model-specific extension parameters

Structure of an input_references item:

{
  "type": "image_url",
  "url": "https://example.com/reference.png"
}

type can be image_url, video_url, or audio_url. Structure of a frame_images item:

{
  "frame_type": "first_frame",
  "image_url": {
    "url": "https://example.com/first-frame.png"
  }
}

frame_type can be first_frame or last_frame.

Media Task Object

Image and video endpoints return the following structure:

{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/videos/task_01K0ABCDEF/content"
    }
  ],
  "error": null,
  "created_at": 1784707200,
  "completed_at": 1784707320,
  "expires_at": null
}

Field	Type	Description
`id`	string	Platform task ID
`object`	string	`image` or `video`
`model`	string	Model name
`status`	string	Current task status
`output`	array	Generated results; an empty array when no result is available
`error`	object/null	Failure details, which may contain `code`, `message`, and `upstream_detail`
`created_at`	integer	Creation time in Unix seconds
`completed_at`	integer/null	Final-status time in Unix seconds
`expires_at`	null	Media-specific endpoints currently return `null`

Media output item:

Field	Type	Description
`index`	integer	Result order, starting from `0`
`type`	string	Currently `file`
`content_url`	string/null	Result download URL
`b64_json`	string/null	Base64-encoded image result

Status Reference

Status	Final	Description
`pending`	No	The platform has accepted the task and it is waiting to run
`in_progress`	No	The task is running
`completed`	Yes	The task is complete and `output` is available
`failed`	Yes	The task failed; see `error` for the reason
`cancelled`	Yes	The task was cancelled

Clients can query every 15 seconds until the status becomes completed, failed, or cancelled. The 15-second interval is a client polling recommendation, not a server protocol limit.

How Do You Query Media Tasks?

Get Media Details

# Image
curl https://aihubmix.com/ai/v1/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# Video
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Media detail endpoints can return an updated task status, so use the corresponding image or video detail endpoint for media polling.

List Media Tasks

If the creation response is lost, use the corresponding media list to recover the task ID:

curl "https://aihubmix.com/ai/v1/videos?limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Parameter	Type	Default	Description
`after`	string	-	Pagination cursor; use `next_after` from the previous page
`limit`	integer	`20`	Number of items per page, maximum `100`
`order`	string	`desc`	`asc` for ascending order; all other values are treated as `desc`

{
  "object": "list",
  "data": [
    {
      "id": "task_01K0ABCDEF",
      "object": "video",
      "model": "wan2.6-t2v",
      "status": "in_progress",
      "output": [],
      "error": null,
      "created_at": 1784707200,
      "completed_at": null,
      "expires_at": null
    }
  ],
  "has_more": true,
  "next_after": "task_01K0ABCDEF"
}

Media lists return task snapshots at query time and do not actively update task status.

How Do You Use the Unified Task API?

The unified task API supports the following filters:

curl "https://aihubmix.com/ai/v1/tasks?object=video&status=in_progress&limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Parameter	Type	Default	Description
`object`	string	-	`llm`, `image`, or `video`
`status`	string	-	`pending`, `in_progress`, `completed`, `failed`, or `cancelled`
`model`	string	-	Exact filter by model name
`after`	string	-	Pagination cursor
`limit`	integer	`20`	Range from `1` to `100`
`order`	string	`desc`	`asc` or `desc`

Unified task details:

curl https://aihubmix.com/ai/v1/tasks/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

A unified output item for a media task:

{
  "index": 0,
  "result_id": "result_01K0XYZ",
  "type": "file",
  "content_type": "video/mp4",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
}

For a single-artifact task, request /ai/v1/tasks/{id}/content directly. For a multi-artifact task, request /ai/v1/tasks/{id}/content/{result_id}. Omitting the result ID returns 400 result_id_required.

Unified task list, detail, and content endpoints are isolated by the Bearer token used to create the task. Other API Keys under the same account cannot read the task.

How Do You Download Media Results?

Download Images

After an image task is completed, request output[].content_url from the media task object for each result:

curl "{content_url}" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png

The media download path for images is /ai/v1/images/{id}/content/{result_id}. The media task object does not expose result_id separately, so clients can use content_url directly. When b64_json is not empty, decode that field directly from Base64.

Download Videos

curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

Results may expire, and download limits may apply. An expired result returns 410 artifact_expired; exceeding the download limit returns 429 too_many_downloads.

How Do You Use Webhooks?

Asynchronous images and videos support task-level webhooks:

curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A tranquil garden at sunrise",
    "duration": 5,
    "size": "1280x720",
    "webhook_url": "https://example.com/webhooks/aihubmix",
    "webhook_events_filter": ["completed", "failed"]
  }'

webhook_url can be up to 512 characters and cannot point to localhost, private networks, or other restricted addresses. When webhook_events_filter is omitted, the platform sends completed, failed, and cancelled. When explicitly provided, the array must not be empty or contain duplicates, and it must be used with webhook_url. When webhook_url is omitted from the request, asynchronous image and video tasks try to use the default callback URL configured for the account. An invalid account default is ignored and does not prevent task creation.

Callback Request

{
  "event_id": "evt_01K0ABCDEF",
  "event_type": "completed",
  "created_at": "2026-08-12T12:00:00Z",
  "data": {
    "task_id": "task_01K0ABCDEF",
    "status": "completed",
    "model": "wan2.6-t2v",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
      }
    ]
  }
}

Field	Description
`event_id`	Callback event ID, used for deduplication
`event_type`	`completed`, `failed`, or `cancelled`
`created_at`	Event time in RFC 3339 format
`data.task_id`	Platform task ID
`data.status`	Current final status
`data.model`	Model name
`data.results[].url`	Result download URL, when available on completion
`data.error`	Error details, when available on failure

results appears only when results have been archived. Downloads still require a Bearer token.

Retries and Deduplication

The platform uses at-least-once delivery, so the same event may be delivered more than once:

HTTP 2xx indicates successful receipt.
HTTP 5xx, network errors, or timeouts trigger a retry.
HTTP 3xx and 4xx are not retried.
Up to 6 delivery attempts are made, with retry intervals of 1, 4, 16, 64, and 256 seconds.

The receiver should store event_id and return 2xx immediately when the same event is received again.

Task-level webhooks do not include a separate signing secret. If signature verification is required, configure an account-level webhook subscription and retain task detail queries as the method for confirming results.

How LLM Interruption Recovery Works

LLM interruption recovery retrieves the final response after the client disconnects. The request method, streaming behavior, and response format remain unchanged, and no task ID is returned in advance when the request starts. All of the following conditions must be met:

Condition	Description
Async tasks are enabled for the account	Enable the feature for the current account in the AIHubMix console
The model supports interruption recovery	The current model appears in the Models for LLM Interruption Recovery list
The endpoint is supported	Chat Completions, Anthropic Messages, Responses API, or Gemini `generateContent` / `streamGenerateContent`
The client is interrupted	The client cancels, the network disconnects, or the caller cancels the request

The platform creates a recovery task and saves the final JSON or SSE only when it detects that the response was not delivered completely and the client has disconnected. LLM requests that finish normally and are delivered completely to the client do not create recovery tasks. LLM response headers contain X-Aihubmix-Request-Id. Clients should save this value as early as possible so the request can be located in the console. The public task API currently cannot filter by request ID. Recent LLM tasks can be queried by model and creation time:

curl "https://aihubmix.com/ai/v1/tasks?object=llm&model={model}&order=desc&limit=20" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl https://aihubmix.com/ai/v1/tasks/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

A unified output item for an LLM task contains type=response, content_type, content_url, and truncated. GET /ai/v1/tasks/{id}/content returns the saved original JSON or SSE.

LLM interruption recovery tasks currently do not send task-level webhooks. A client interruption does not stop the platform from continuing to process the request, and the call is still billed according to the rules of the original endpoint.

Error Responses and Error Codes

This section applies to /ai/v1/images/*, /ai/v1/videos/*, and media tasks under /ai/v1/tasks/* where object=image or object=video. Clients must handle both non-2xx HTTP responses and terminal tasks returned with HTTP 200 and status=failed.

{
  "error": {
    "message": "Task not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0ABCDEF"
  }
}

Submit HTTP 5xx error feedback

Only when a request returns HTTP 5xx, submit feedback and include error.tid.

Non-2xx HTTP Errors

The invalid_request and schema_violation rows show fallback messages. When the service can identify a specific field or parameter constraint, it returns a dynamic message. Clients should classify errors by code instead of exact-matching message.

HTTP	`code`	`message`	Description
400	`invalid_request`	`Invalid request. Check the request body and parameters.` (fallback template; the actual message may be dynamic)	The common request body, field types, or list parameters are invalid; this code’s message is not fixed, and a more specific dynamic message is returned when the field can be identified
400	`model_not_found`	`The requested model is not available. Check the model name and your account access.`	The model does not exist, is unavailable, or is not accessible to the current account
400	`schema_violation`	`Invalid request: one or more parameters are invalid.` (fallback template; the actual message may be dynamic)	The request does not match the current model’s parameter schema; this code’s message is not fixed, and a field-level dynamic message is returned when the field or constraint can be identified
400	`capability_not_supported`	`The requested parameters are not supported for this model.`	The current model does not support a requested field, count, or parameter limit
400	`media_form_unsupported`	Dynamic media message; see below	The format, data, URL, or size of an image, video, reference image, or first/last frame cannot be processed
400	`result_id_required`	`This task has multiple results. Specify result_id.`	The task has multiple results, but `result_id` was omitted from the download request
400	`upstream_rejected`	`Upstream service rejected the request.`	The model provider rejected the creation request
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	The API Key is missing or invalid
402	`insufficient_quota`	`Insufficient quota.`	The AIHubMix account has insufficient available quota
403	`permission_denied`	`You do not have permission to access this resource.`	The current account, API Key, or request origin is not permitted to use the resource
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to <console-url>/async-tasks to activate.`	Asynchronous tasks are not enabled for the account; the console URL is generated from the request site
404	`task_not_found`	`Task not found.`	The task does not exist, the pagination cursor is invalid, or the current account cannot view it
404	`result_not_found`	`Result not found.`	The result does not exist, is not ready, has a mismatched result ID, or cannot be downloaded by the current account
410	`artifact_expired`	`The result has expired.`	The result has exceeded its retention period
413	`request_too_large`	`Request body is too large. Reduce the request size and try again.`	The complete request body exceeds 32 MiB
413	`image_too_large`	`Image is too large. Reduce the image size and try again.`	A decoded image submitted to an image endpoint exceeds the model’s processing limit
422	`image_not_generated`	`The expected image was not generated.`	The model provider completed the request but did not return a deliverable image
429	`rate_limited`	`Too many requests. Please slow down and retry.`	AIHubMix is rate limiting the current account or API Key
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	The model provider returned a rate-limit error
429	`too_many_downloads`	`Download limit exceeded for this result.`	A single result has reached its download limit
500	`internal_error`	`Internal error. Please retry.`	The service encountered an internal error that the caller cannot correct
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	The model provider could not be reached, or its response could not be read completely
502	`upstream_bad_response`	`Upstream service returned an invalid response.`	The model provider returned a response that the platform could not process
502	`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	The model provider returned a service error
503	`model_unavailable`	`The requested model is temporarily unavailable.`	The selected model is temporarily unavailable
503	`service_unavailable`	`Service is temporarily unavailable. Please retry.`	The query, download, or result service is temporarily unavailable
504	`sync_timeout`	`Generation timed out. Please retry.`	Synchronous generation did not finish within the waiting period

The message for media_form_unsupported is generated from the confirmed cause. Common templates are listed below:

Scenario	`message`
Unsupported format	`Unsupported <media-kind> format: <detected-format>. Supported formats for this model: <allowed-formats>.`
Invalid image or video data	`The <media-kind> data is invalid. Provide a valid <media-kind>.`
Invalid data when the media type cannot be determined	`The media data is invalid. Provide valid media data.`
Inaccessible media URL	`The <media-kind> URL could not be accessed. Make sure it is publicly accessible and returns a valid <media-kind>.`
Media cannot be decoded	`Unable to process the <media-kind>. Check that the <media-kind> data or URL is valid and supported.`
Media exceeds the limit for a non-image task	`The <media-kind> is too large. Reduce the <media-kind> size and try again.`
The specific cause cannot be determined safely	`Unable to process the media. Check that the media data or URL is valid and supported.`

For example, if the model allows PNG, JPEG, WebP, HEIC, and HEIF, a GIF image returns:

Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF.

HTTP 200 + Task `status=failed`

A successful query does not mean that generation succeeded. When a task is failed, read the failure reason from error.code and error.message in the task object:

{
  "id": "task_01K0ABCDEF",
  "status": "failed",
  "error": {
    "code": "media_form_unsupported",
    "message": "Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF."
  }
}

Task `code`	`message`	Description
`media_form_unsupported`	Dynamic media message; same as above	The asynchronous task has a media format, data, URL, decoding, or size error
`image_too_large`	`Image is too large. Reduce the image size and try again.`	An input image for an asynchronous image task exceeds the limit
`image_not_generated`	`The expected image was not generated.`	The model provider did not return a deliverable image
`upstream_rejected`	`Upstream service rejected the request.`	The model provider rejected the creation request
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	The model provider returned a rate-limit error
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	The model provider could not be reached while creating the task, or its response could not be read completely
`upstream_bad_response`	`Upstream service returned an invalid response.`	The model provider’s response could not be processed
`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	The model provider failed while creating or executing the task
`upstream_empty_output`	`The upstream service completed without producing a usable result. Please retry.`	The model provider completed the task without producing a deliverable result
`output_policy_violation`	`Generated content was rejected by the content policy.`	The generated content did not pass the content safety policy
`sync_timeout`	`Generation timed out. Please retry.`	Waiting for the generation result timed out
`internal_error`	`Internal error. Please retry.`	An internal error occurred while processing the asynchronous task

Complete Video Example

import os
import time

import requests

base_url = "https://aihubmix.com"
headers = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/ai/v1/videos",
    headers=headers,
    json={
        "model": "wan2.6-t2v",
        "prompt": "A cat playing jazz on a piano",
        "duration": 5,
        "size": "1280x720",
    },
    timeout=60,
)
response.raise_for_status()
task = response.json()

while task["status"] not in {"completed", "failed", "cancelled"}:
    time.sleep(15)
    response = requests.get(
        f"{base_url}/ai/v1/videos/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] == "completed":
    result = requests.get(
        f"{base_url}/ai/v1/videos/{task['id']}/content",
        headers=headers,
        timeout=120,
    )
    result.raise_for_status()
    with open("result.mp4", "wb") as file:
        file.write(result.content)
else:
    raise RuntimeError(task.get("error") or task["status"])

import { writeFile } from "node:fs/promises";

const baseUrl = "https://aihubmix.com";
const headers = {
  Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch(`${baseUrl}/ai/v1/videos`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "wan2.6-t2v",
    prompt: "A cat playing jazz on a piano",
    duration: 5,
    size: "1280x720",
  }),
});
if (!created.ok) throw new Error(await created.text());
let task = await created.json();

const finished = new Set(["completed", "failed", "cancelled"]);
while (!finished.has(task.status)) {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  const polled = await fetch(`${baseUrl}/ai/v1/videos/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status === "completed") {
  const result = await fetch(`${baseUrl}/ai/v1/videos/${task.id}/content`, {
    headers,
  });
  if (!result.ok) throw new Error(await result.text());
  await writeFile("result.mp4", Buffer.from(await result.arrayBuffer()));
} else {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

FAQ

Should a media task be queried through /ai/v1/tasks/{id} or the media detail endpoint? Use the media detail endpoint to poll generation status: /ai/v1/images/{id} for images and /ai/v1/videos/{id} for videos. /ai/v1/tasks/{id} returns a read-only snapshot. Why does seconds in a video request return a parameter error? The standard /ai/v1/videos protocol uses the integer field duration, measured in seconds. The allowed values depend on the parameters supported by the corresponding model. Why does resolution return a parameter error for some video models? The standard video protocol includes resolution and size, but individual models narrow the supported fields. For example, wan2.6-t2v uses size and does not accept resolution. How can a media task be recovered after the creation response is lost? Request GET /ai/v1/images for images or GET /ai/v1/videos for videos. The lists support the after, limit, and order pagination parameters. Why do the two detail endpoints have different output fields? Media detail endpoints provide the simplified fields required for direct downloads. Unified task endpoints additionally provide result_id and content_type, as well as truncated for archived LLM responses. What should I do if a webhook is not received? Confirm that the callback URL is publicly accessible and returns 2xx promptly, then query the final status through the media detail endpoint.

Last updated: 2026-08-12

Video tutorial: Async Tasks

Enable async tasks in the console

​Quickstart

​Which API Group Should You Use?

​Media Endpoints and Unified Task Endpoints

​How Do You Discover Async Media Models and Get Their Schemas?

​List Models That Support the Async APIs

​Get the Request Schema for One Model

​Which Models and Fields Are Supported?

​Models for LLM Interruption Recovery

​How Do You Create Image Tasks?

​Synchronous Images

​Asynchronous Images

​Standard Image Fields

​How Do You Create Video Tasks?

​Standard Video Fields

​Media Task Object

​Status Reference

​How Do You Query Media Tasks?

​Get Media Details

​List Media Tasks

​How Do You Use the Unified Task API?

​How Do You Download Media Results?

​Download Images

​Download Videos

​How Do You Use Webhooks?

​Callback Request

​Retries and Deduplication

​How LLM Interruption Recovery Works

​Error Responses and Error Codes

Submit HTTP 5xx error feedback

​Non-2xx HTTP Errors

​HTTP 200 + Task status=failed

​Complete Video Example

​FAQ

Quickstart

Which API Group Should You Use?

Media Endpoints and Unified Task Endpoints

How Do You Discover Async Media Models and Get Their Schemas?

List Models That Support the Async APIs

Get the Request Schema for One Model

Which Models and Fields Are Supported?

Models for LLM Interruption Recovery

How Do You Create Image Tasks?

Synchronous Images

Asynchronous Images

Standard Image Fields

How Do You Create Video Tasks?

Standard Video Fields

Media Task Object

Status Reference

How Do You Query Media Tasks?

Get Media Details

List Media Tasks

How Do You Use the Unified Task API?

How Do You Download Media Results?

Download Images

Download Videos

How Do You Use Webhooks?

Callback Request

Retries and Deduplication

How LLM Interruption Recovery Works

Error Responses and Error Codes

Non-2xx HTTP Errors

HTTP 200 + Task `status=failed`

Complete Video Example

FAQ