画像生成

クイックスタート

ネイティブ画像エンドポイントはデフォルトで同期です。Boolean の 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 を取得する方法

ディスカバリーは 2 段階です。まず、公開モデルカタログから非同期 API に対応する画像生成または動画生成モデルを取得します。次に、モデルの model_id を使って、そのエンドポイントのリクエスト Schema を取得します。

非同期 API 対応モデルの一覧を取得する

モデルカタログは 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"

どちらも同じ API を使用します。現在、type フィルターは 1 つの値を受け付けるため、モデルタイプごとにリクエストしてください。レスポンスの形は {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
    }
  ]
}

1 つのモデルのリクエスト Schema を取得する

対応するフィールド、列挙値、数値範囲はモデルごとに異なります。画像または動画のリクエストを送信する前に、次の公開 API で対象モデルの利用可能なエンドポイントとリクエスト 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` などの HTTP メソッド
`endpoints[].path`	実際のリクエストパス
`endpoints[].content_types`	エンドポイントが受け付けるコンテンツタイプ
`endpoints[].lifecycle`	同期または非同期モード、ポーリングパス、ステータス値
`endpoints[].request.schema`	必須フィールドと値の制約を含む、そのモデルとエンドポイントの完全な JSON Schema

同じモデルで /ai/v1 エンドポイントと OpenAI 互換の /v1 エンドポイントが返される場合があります。OpenAI 互換エンドポイントは最新モデルにまだ対応していない可能性があるため、/ai/v1 エンドポイントを優先してください。非同期タスク API では、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 に設定すると、API は生成が完了するまで待機し、タスクオブジェクトを返します。

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 に設定すると、API はすぐにタスクオブジェクトを返し、生成処理はバックグラウンドで続行されます。

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	いいえ	1 枚の入力画像。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 コールバック URL。最大 512 文字
`webhook_events_filter`	string[]	いいえ	`completed`、`failed`、`cancelled` の空でないサブセット
`extra`	object/null	いいえ	モデル固有の拡張パラメータ

メディアタスクオブジェクト

画像と動画の専用 API は、次の構造を返します。

{
  "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	メディア専用 API では現在 `null` を返す

メディアの output 項目：

フィールド	型	説明
`index`	integer	結果の順番。`0` から始まる
`type`	string	現在は `file`
`content_url`	string/null	結果のダウンロード URL
`b64_json`	string/null	Base64 エンコードされた画像結果

ステータスの説明

ステータス	終了済みか	説明
`pending`	いいえ	プラットフォームがタスクを受け付け、実行を待っている
`in_progress`	いいえ	タスクを実行中
`completed`	はい	タスクが完了し、`output` を読み取り可能
`failed`	はい	タスクが失敗。理由は `error` を参照
`cancelled`	はい	タスクがキャンセルされた

クライアントは、ステータスが completed、failed、cancelled のいずれかになるまで、15 秒ごとに照会できます。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"

メディア詳細 API は更新後のタスクステータスを返す場合があるため、メディアのポーリングには該当する画像または動画の詳細 API を使用してください。

メディア一覧の照会

作成レスポンスを失った場合は、該当するメディア一覧からタスク 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`	1 ページあたりの件数。最大 `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"
}

メディア一覧は照会時点のタスクスナップショットを返し、タスクステータスを能動的に更新することはありません。

統一タスク API を使用する方法

統一タスク API では、次の条件で絞り込めます。

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 が返されます。

統一タスクの一覧、詳細、コンテンツ API は、タスク作成時の 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 を渡さなかった場合、非同期画像と動画ではアカウントに設定されたデフォルトのコールバック URL が使用されます。アカウントのデフォルト 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`	完了時に返される場合がある結果のダウンロード URL
`data.error`	失敗時に返される場合があるエラー情報

results は結果がアーカイブ済みの場合にのみ含まれ、ダウンロードには引き続き Bearer Token が必要です。

リトライと重複排除

プラットフォームは少なくとも 1 回の配信を行うため、同じイベントが複数回届く場合があります。

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 を取得する方法

非同期 API 対応モデルの一覧を取得する

1 つのモデルのリクエスト Schema を取得する

画像タスクを作成する方法

同期画像

非同期画像

画像の標準フィールド

メディアタスクオブジェクト

ステータスの説明

メディアタスクを照会する方法

メディア詳細の照会

メディア一覧の照会

統一タスク API を使用する方法

メディア結果をダウンロードする方法

画像のダウンロード

Webhook を使用する方法

コールバックリクエスト

リトライと重複排除

エラーレスポンスとエラーコード

完全な例

​クイックスタート

​非同期メディアモデルを見つけて Schema を取得する方法

​非同期 API 対応モデルの一覧を取得する

​1 つのモデルのリクエスト Schema を取得する

​画像タスクを作成する方法

​同期画像

​非同期画像

​画像の標準フィールド

​メディアタスクオブジェクト

​ステータスの説明

​メディアタスクを照会する方法

​メディア詳細の照会

​メディア一覧の照会

​統一タスク API を使用する方法

​メディア結果をダウンロードする方法

​画像のダウンロード

​Webhook を使用する方法

​コールバックリクエスト

​リトライと重複排除

​エラーレスポンスとエラーコード

​完全な例

クイックスタート

非同期メディアモデルを見つけて Schema を取得する方法

非同期 API 対応モデルの一覧を取得する

1 つのモデルのリクエスト Schema を取得する

画像タスクを作成する方法

同期画像

非同期画像

画像の標準フィールド

メディアタスクオブジェクト

ステータスの説明

メディアタスクを照会する方法

メディア詳細の照会

メディア一覧の照会

統一タスク API を使用する方法

メディア結果をダウンロードする方法

画像のダウンロード

Webhook を使用する方法

コールバックリクエスト

リトライと重複排除

エラーレスポンスとエラーコード

完全な例