Video Generation

Quickstart

Video generation is always asynchronous. This example uses wan2.6-t2v and an integer duration in 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"
  }'

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

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

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

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.

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 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.

Error Responses and Error Codes

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

HTTP status	Error code	Description
400	`invalid_request`	Incorrect parameter type or value
400	`result_id_required`	The unified task has multiple results, but `result_id` was omitted from the download request
400	`webhook_invalid`	The webhook URL is invalid, or the filter is provided without a URL
400	`webhook_events_filter_invalid`	The webhook event list is invalid
401	`authentication_failed`	The API Key is missing or invalid
403	`async_not_enabled`	Async tasks are not enabled for the account
404	`task_not_found`	The task or pagination cursor does not exist
404	`result_not_found`	The result does not exist or cannot currently be downloaded
410	`artifact_expired`	The result has expired
413	`request_too_large`	The request body exceeds 32 MiB
429	`too_many_downloads`	The result download limit has been exceeded
503	`async_unavailable`	The asynchronous image service is temporarily unavailable

error.tid is the request trace ID. Include it when contacting technical support for troubleshooting.

Complete example

These examples create a task, poll it, and download the MP4 result.

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));
}

Getting Started

Gateway Features

Model Capabilities

Protocol Reference

Platform Management

Privacy & Terms

Quickstart

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

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 Videos

How Do You Use Webhooks?

Callback Request

Retries and Deduplication

Error Responses and Error Codes

Complete example

​Quickstart

​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

​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 Videos

​How Do You Use Webhooks?

​Callback Request

​Retries and Deduplication

​Error Responses and Error Codes

​Complete example

Quickstart

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

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 Videos

How Do You Use Webhooks?

Callback Request

Retries and Deduplication

Error Responses and Error Codes

Complete example