影片生成

快速開始

影片生成固定為非同步；以下使用 wan2.6-t2v，並以整數 duration 表示秒數。

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

如何探索非同步媒體模型並取得 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。

如何建立影片任務

影片請求一律非同步，不支援透過 Prefer: wait 改為同步等待。標準協定使用整數 duration 表示秒數：

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

影片標準欄位

欄位	類型	必填	說明
`model`	string	是	模型名稱
`prompt`	string	是	影片描述，不可為空
`duration`	integer/null	否	影片時長，單位為秒；具體範圍由模型決定
`aspect_ratio`	string/null	否	長寬比，協定預設值為 `16:9`
`resolution`	string/null	否	`480p`、`720p`、`1080p`、`1K`、`2K` 或 `4K`
`size`	string/null	否	`{width}x{height}`；可取代 `resolution` 與 `aspect_ratio`
`seed`	integer/null	否	隨機種子
`input_references`	array/null	否	圖片、影片或音訊參考素材
`frame_images`	array/null	否	首幀或尾幀圖片
`generate_audio`	boolean/null	否	是否生成音軌
`webhook_url`	string	否	HTTPS 回呼位址，最長 512 個字元
`webhook_events_filter`	string[]	否	`completed`、`failed`、`cancelled` 的非空子集
`extra`	object/null	否	特定模型的擴充參數

input_references 項目的結構：

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

type 可以是 image_url、video_url 或 audio_url。 frame_images 項目的結構：

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

frame_type 可以是 first_frame 或 last_frame。

媒體任務物件

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

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

欄位	類型	說明
`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/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

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

查詢媒體清單

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

curl "https://aihubmix.com/ai/v1/videos?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": "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"
}

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

如何使用統一任務介面

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

curl "https://aihubmix.com/ai/v1/tasks?object=video&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": "video/mp4",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
}

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

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

如何下載媒體結果

下載影片

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

結果可能過期，並且可能存在下載次數限制。過期回傳 410 artifact_expired，超過下載次數限制回傳 429 too_many_downloads。

如何使用 Webhook

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

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 最長 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": "wan2.6-t2v",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
      }
    ]
  }
}

欄位	說明
`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，聯絡技術支援排查時請一併提供。

完整範例

以下範例會建立任務、輪詢並下載 MP4。

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

開始使用

閘道能力

模型能力

協定參考

平台管理

隱私和條款

快速開始

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

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

取得單一模型的請求 Schema

如何建立影片任務

影片標準欄位

媒體任務物件

狀態說明

如何查詢媒體任務

查詢媒體詳情

查詢媒體清單

如何使用統一任務介面

如何下載媒體結果

下載影片

如何使用 Webhook

回呼請求

重試與去重

錯誤回應與錯誤碼

完整範例

​快速開始

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

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

​取得單一模型的請求 Schema

​如何建立影片任務

​影片標準欄位

​媒體任務物件

​狀態說明

​如何查詢媒體任務

​查詢媒體詳情

​查詢媒體清單

​如何使用統一任務介面

​如何下載媒體結果

​下載影片

​如何使用 Webhook

​回呼請求

​重試與去重

​錯誤回應與錯誤碼

​完整範例

快速開始

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

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

取得單一模型的請求 Schema

如何建立影片任務

影片標準欄位

媒體任務物件

狀態說明

如何查詢媒體任務

查詢媒體詳情

查詢媒體清單

如何使用統一任務介面

如何下載媒體結果

下載影片

如何使用 Webhook

回呼請求

重試與去重

錯誤回應與錯誤碼

完整範例