圖片生成

快速開始

原生圖片端點預設同步。將布林值 async 設為 true 可建立背景任務；以下使用 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

如何探索非同步媒體模型並取得 Schema

探索流程分為兩個步驟。先從公開模型目錄取得支援非同步介面的文生圖或文生影片模型，再使用模型的 model_id 取得對應端點的請求 Schema。

取得支援非同步介面的模型清單

模型目錄與 Playground 使用相同的資料來源。type=image_generation 回傳文生圖模型，type=video 回傳文生影片模型。加入 schema_checked=true 後，清單只包含已發布並核對請求 Schema 的模型。

# 文生圖模型
curl "https://aihubmix.com/api/v1/models?type=image_generation&schema_checked=true&sort_by=order"

# 文生影片模型
curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order"

兩個請求使用同一個介面。type 篩選目前只接受一個值，因此需要分別請求兩種模型類型。回應格式為 {success, message, data}。data 中與非同步媒體整合相關的欄位如下。

欄位	說明
`data[].model_id`	用於生成請求和後續 Schema 查詢的模型 ID
`data[].model_name`	模型顯示名稱
`data[].types`	逗號分隔的模型類型，可能同時包含 `image_generation` 和 `llm`
`data[].input_modalities`	逗號分隔的輸入模態
`data[].schema_checked`	`true` 代表請求 Schema 已發布並完成核對

{
  "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
    }
  ]
}

取得單一模型的請求 Schema

不同模型支援的欄位、列舉和數值範圍可能不同。提交圖片或影片請求前，可以透過同一個公開介面取得指定模型目前可用的端點和請求 JSON Schema。

# 文生圖模型
curl "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints"

# 文生影片模型
curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints"

回應中的 modality 為 image 或 video。endpoints 陣列中的每一項描述一個可用的呼叫協定。

欄位	說明
`default_endpoint`	目前模型的預設端點識別碼
`endpoints[].endpoint`	端點識別碼
`endpoints[].method`	請求方法，例如 `POST`
`endpoints[].path`	實際提交路徑
`endpoints[].content_types`	端點接受的內容類型
`endpoints[].lifecycle`	同步或非同步模式、輪詢路徑和狀態值
`endpoints[].request.schema`	該模型在對應端點下的完整請求 JSON Schema，包括必填欄位和取值限制

同一個模型可能同時回傳 /ai/v1 與 OpenAI 相容 /v1 端點。OpenAI 相容介面可能暫不支援最新模型，請優先使用 /ai/v1 端點。非同步任務介面應依 path 選擇 /ai/v1/images/generations 或 /ai/v1/videos，再讀取該項目的 request.schema。不要依賴 endpoints 陣列位置。下面的命令可以直接擷取兩個非同步任務端點的請求 Schema。

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

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

模型不存在或尚未提供可探索端點時，介面回傳 404 model_not_found。端點資料暫時無法使用時回傳 500 endpoints_unavailable。

如何建立圖片任務

同步圖片

省略 async 或設定為 false 時，介面會等待生成完成並回傳任務物件：

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"
  }'

同步圖片任務也會儲存任務記錄。用戶端連線中斷或建立回應遺失時，可以透過 GET /ai/v1/images 尋找對應任務。

非同步圖片

將 async 設定為布林值 true 後，介面會立即回傳任務物件，生成在背景繼續：

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

使用 GET /ai/v1/images/{id} 查詢非同步圖片任務。完成後，直接請求每個 output 項目中的 content_url；該 URL 已包含對應圖片的 result_id。

圖片請求中的 async 必須是布林值。webhook_url 和 webhook_events_filter 僅能與 async: true 一起使用。

圖片標準欄位

欄位	類型	必填	說明
`model`	string	是	模型名稱
`prompt`	string	是	圖片描述，不可為空
`n`	integer/null	否	圖片數量，最小值 `1`，預設 `1`
`size`	string/null	否	`{width}x{height}`，例如 `1024x1024`
`aspect_ratio`	string/null	否	長寬比；與 `size` 二選一
`seed`	integer/null	否	隨機種子
`negative_prompt`	string/null	否	負向提示詞
`image`	string/object	否	單張輸入圖片，可以是 URL、Data URI、Base64 或 `{url}` 物件
`images`	array/null	否	多張輸入圖片
`mask`	string/object	否	圖片編輯遮罩
`output_format`	string/null	否	`png`、`jpeg` 或 `webp`，預設 `png`
`response_format`	string/null	否	`url` 或 `b64_json`，預設 `url`
`async`	boolean	否	設為 `true` 時非同步執行
`webhook_url`	string	否	HTTPS 回呼位址，最長 512 個字元
`webhook_events_filter`	string[]	否	`completed`、`failed`、`cancelled` 的非空子集
`extra`	object/null	否	特定模型的擴充參數

媒體任務物件

圖片和影片專用介面回傳以下結構：

{
  "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
}

欄位	類型	說明
`id`	string	平台任務 ID
`object`	string	`image` 或 `video`
`model`	string	模型名稱
`status`	string	目前任務狀態
`output`	array	已生成的結果；尚無結果時為空陣列
`error`	object/null	失敗資訊，可包含 `code`、`message` 和 `upstream_detail`
`created_at`	integer	建立時間，Unix 秒
`completed_at`	integer/null	最終狀態時間，Unix 秒
`expires_at`	null	媒體專用介面目前回傳 `null`

媒體 output 項目：

欄位	類型	說明
`index`	integer	結果順序，從 `0` 開始
`type`	string	目前為 `file`
`content_url`	string/null	結果下載位址
`b64_json`	string/null	Base64 編碼的圖片結果

狀態說明

狀態	是否結束	說明
`pending`	否	平台已接收任務，等待執行
`in_progress`	否	任務正在執行
`completed`	是	任務完成，可讀取 `output`
`failed`	是	任務失敗，原因請見 `error`
`cancelled`	是	任務已取消

用戶端可以每 15 秒查詢一次，直到狀態變為 completed、failed 或 cancelled。15 秒是用戶端輪詢建議，不是伺服器協定限制。

如何查詢媒體任務

查詢媒體詳情

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

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

媒體詳情介面可回傳更新後的任務狀態，因此媒體輪詢應使用對應的圖片或影片詳情介面。

查詢媒體清單

建立回應遺失時，可以透過對應媒體清單找回任務 ID：

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

參數	類型	預設值	說明
`after`	string	-	分頁游標，使用上一頁的 `next_after`
`limit`	integer	`20`	每頁數量，最大 `100`
`order`	string	`desc`	傳入 `asc` 時升冪，其他值按 `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"
}

媒體清單回傳查詢時的任務快照，不會主動更新任務狀態。

如何使用統一任務介面

統一任務介面支援以下篩選條件：

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

參數	類型	預設值	說明
`object`	string	-	`llm`、`image` 或 `video`
`status`	string	-	`pending`、`in_progress`、`completed`、`failed` 或 `cancelled`
`model`	string	-	按模型名稱精確篩選
`after`	string	-	分頁游標
`limit`	integer	`20`	範圍 `1` 到 `100`
`order`	string	`desc`	`asc` 或 `desc`

統一任務詳情：

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

媒體任務的統一 output 項目：

{
  "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"
}

單一產物直接請求 /ai/v1/tasks/{id}/content。多產物任務需要請求 /ai/v1/tasks/{id}/content/{result_id}；未指定結果 ID 時回傳 400 result_id_required。

統一任務清單、詳情和內容介面按建立任務時的 Bearer Token 隔離。同一帳戶下的其他 API Key 無法讀取該任務。

如何下載媒體結果

下載圖片

圖片完成後，逐項請求媒體任務物件中的 output[].content_url：

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

圖片的媒體下載路徑為 /ai/v1/images/{id}/content/{result_id}。媒體任務物件不另外公開 result_id，用戶端直接使用 content_url 即可。當 b64_json 非空時，可以直接對該欄位進行 Base64 解碼。

如何使用 Webhook

非同步圖片和影片支援任務層級 Webhook：

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 最長 512 個字元，並且不能指向本機、私人網路或其他受限位址。省略 webhook_events_filter 時，平台推送 completed、failed 和 cancelled；明確傳入時，陣列不可為空、不可重複，並且必須與 webhook_url 一起使用。未在請求中傳入 webhook_url 時，非同步圖片和影片會嘗試使用帳戶中設定的預設回呼位址。無效的帳戶預設位址會被忽略，不會阻止任務建立。

回呼請求

{
  "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"
      }
    ]
  }
}

欄位	說明
`event_id`	回呼事件 ID，用於去重
`event_type`	`completed`、`failed` 或 `cancelled`
`created_at`	RFC 3339 格式的事件時間
`data.task_id`	平台任務 ID
`data.status`	目前最終狀態
`data.model`	模型名稱
`data.results[].url`	完成時可能回傳的結果下載位址
`data.error`	失敗時可能回傳的錯誤資訊

results 僅在結果已存檔時出現，下載仍需要 Bearer Token。

重試與去重

平台採用至少一次投遞，同一個事件可能重複送達：

HTTP 2xx 表示接收成功。
HTTP 5xx、網路錯誤或逾時會觸發重試。
HTTP 3xx 和 4xx 不會重試。
最多投遞 6 次，重試間隔依序為 1、4、16、64、256 秒。

接收端應儲存 event_id，重複收到相同事件時直接回傳 2xx。

任務層級 Webhook 本身不含獨立簽章金鑰。需要簽章驗證時，請設定帳戶層級 Webhook 訂閱，並保留任務詳情查詢作為結果確認方式。

錯誤回應與錯誤碼

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

HTTP 狀態碼	錯誤碼	說明
400	`invalid_request`	參數類型或值不正確
400	`result_id_required`	統一任務有多個結果，但下載時未指定 `result_id`
400	`webhook_invalid`	Webhook URL 不合法，或篩選器缺少 URL
400	`webhook_events_filter_invalid`	Webhook 事件清單不合法
401	`authentication_failed`	API Key 缺少或無效
403	`async_not_enabled`	帳戶未開啟非同步任務功能
404	`task_not_found`	任務或分頁游標不存在
404	`result_not_found`	結果不存在或目前無法下載
410	`artifact_expired`	結果已過期
413	`request_too_large`	請求本文超過 32 MiB
429	`too_many_downloads`	超過結果下載次數限制
503	`async_unavailable`	非同步圖片服務暫時無法使用

error.tid 是請求追蹤 ID，聯絡技術支援排查時請一併提供。

完整範例

以下範例會建立非同步任務、輪詢並儲存所有回傳圖片。

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

開始使用

閘道能力

模型能力

協定參考

平台管理

隱私和條款

快速開始

如何探索非同步媒體模型並取得 Schema

取得支援非同步介面的模型清單

取得單一模型的請求 Schema

如何建立圖片任務

同步圖片

非同步圖片

圖片標準欄位

媒體任務物件

狀態說明

如何查詢媒體任務

查詢媒體詳情

查詢媒體清單

如何使用統一任務介面

如何下載媒體結果

下載圖片

如何使用 Webhook

回呼請求

重試與去重

錯誤回應與錯誤碼

完整範例

​快速開始

​如何探索非同步媒體模型並取得 Schema

​取得支援非同步介面的模型清單

​取得單一模型的請求 Schema

​如何建立圖片任務

​同步圖片

​非同步圖片

​圖片標準欄位

​媒體任務物件

​狀態說明

​如何查詢媒體任務

​查詢媒體詳情

​查詢媒體清單

​如何使用統一任務介面

​如何下載媒體結果

​下載圖片

​如何使用 Webhook

​回呼請求

​重試與去重

​錯誤回應與錯誤碼

​完整範例

快速開始

如何探索非同步媒體模型並取得 Schema

取得支援非同步介面的模型清單

取得單一模型的請求 Schema

如何建立圖片任務

同步圖片

非同步圖片

圖片標準欄位

媒體任務物件

狀態說明

如何查詢媒體任務

查詢媒體詳情

查詢媒體清單

如何使用統一任務介面

如何下載媒體結果

下載圖片

如何使用 Webhook

回呼請求

重試與去重

錯誤回應與錯誤碼

完整範例