Image Generation

Quickstart

The native image endpoint is synchronous by default. Set the Boolean field async to true to create a background task. This example uses qwen-image-2.0.

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",
    "async": true
  }'

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

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

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

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

Media Task Object

Image and video endpoints return the following structure:

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/images/task_01K0ABCDEF/content/result_01K0XYZ"
    }
  ],
  "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/images/{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/images?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": "image",
      "model": "qwen-image-2.0",
      "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=image&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": "image/png",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
}

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.

How Do You Use Webhooks?

Asynchronous images and videos support task-level webhooks:

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 tranquil garden at sunrise",
    "n": 1,
    "async": true,
    "size": "1024x1024",
    "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": "qwen-image-2.0",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
      }
    ]
  }
}

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 an asynchronous task, poll it, and save every returned image.

import base64
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/images/generations",
    headers=headers,
    json={
        "model": "qwen-image-2.0",
        "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
        "n": 1,
        "size": "1024x1024",
        "async": True,
    },
    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/images/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(task.get("error") or task["status"])

for output in task["output"]:
    filename = f"result-{output['index']}.png"
    if output.get("b64_json"):
        content = base64.b64decode(output["b64_json"])
    else:
        result = requests.get(output["content_url"], headers=headers, timeout=120)
        result.raise_for_status()
        content = result.content
    with open(filename, "wb") as file:
        file.write(content)

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/images/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "qwen-image-2.0",
    prompt: "A flower shop with delicate windows, warm sunlight streaming in",
    n: 1,
    size: "1024x1024",
    async: true,
  }),
});
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/images/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status !== "completed") {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

for (const output of task.output) {
  let content;
  if (output.b64_json) {
    content = Buffer.from(output.b64_json, "base64");
  } else {
    const result = await fetch(output.content_url, { headers });
    if (!result.ok) throw new Error(await result.text());
    content = Buffer.from(await result.arrayBuffer());
  }
  await writeFile(`result-${output.index}.png`, content);
}

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 Image Tasks?

Synchronous Images

Asynchronous Images

Standard Image 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

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 Image Tasks?

​Synchronous Images

​Asynchronous Images

​Standard Image 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

​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 Image Tasks?

Synchronous Images

Asynchronous Images

Standard Image 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

How Do You Use Webhooks?

Callback Request

Retries and Deduplication

Error Responses and Error Codes

Complete example