画像生成

クイックスタート

ネイティブ画像エンドポイントはデフォルトで同期です。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 サブスクリプションを設定し、結果の確認手段としてタスク詳細の照会も維持してください。

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

この節は /ai/v1/images/* と画像タスクに適用されます。動画のエラーは動画 APIをご覧ください。

現在のリクエストの失敗：HTTP が 2xx 以外の場合、今回の作成、照会、ダウンロードに失敗しています。HTTP リクエストの失敗をご覧ください。
タスク実行の失敗：照会は HTTP 200 を返しますが、タスクが status=failed となり、理由はタスク内の error に記録されます。タスク実行の失敗をご覧ください。
一覧の個別結果の読み取り失敗：一覧は HTTP 200 を返しますが、一部のタスクに output_error が含まれます。一覧の個別結果の読み取り失敗をご覧ください。

以下の message 列は API が返す英語のメッセージ、説明列は意味と対処方法を示します。パラメータ検証エラーには一般的なメッセージを掲載しており、実際のレスポンスではフィールドや制約が具体的に示される場合があります。エラーの種類は code で判定し、message 全文の完全一致に依存しないでください。

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

HTTP 5xx エラーの報告

リクエストが HTTP 5xx を返した場合は、error.tid を添えて報告してください。

HTTP リクエストの失敗

以下の HTTP ステータスは、現在のリクエスト自体が失敗した場合に適用されます。作成済みタスクの実行失敗は、後述の「タスク実行の失敗」をご覧ください。

リクエストパラメータとメディア入力

HTTP	`code`	`message`	説明
400	`invalid_request`	`Invalid request. Check the request body and parameters.`	リクエスト本文、クエリパラメータ、またはパラメータの型が不正です。エラーメッセージに従って形式、型、値を確認してください。
404	`model_not_found`	`The requested model was not found. Check the model name.`	指定したモデルが存在しません。モデル名を確認してください。
400	`schema_violation`	`One or more model parameters are invalid. Check the model schema and request values.`	パラメータが選択したモデルの入力要件を満たしていません。モデルの schema を確認し、エラーで示されたフィールドを修正してください。
400	`unsupported_input_combination`	`This model does not support this operation or media input combination. Change the inputs or choose another model.`	このモデルは、指定した操作とメディア入力の組み合わせに対応していません。入力の組み合わせを変更するか、対応するモデルを選択してください。
400	`capability_not_supported`	`One or more requested parameters are not supported by this model. Change the parameters or choose another model.`	リクエストパラメータがモデルの対応範囲を超えています。エラーに従ってパラメータを変更するか、別のモデルを選択してください。
400	`unsupported_media_format`	`The {media_kind} format is not supported for this model.`	このモデルは現在のメディア形式に対応していません。エラーメッセージまたは `error.details.allowed_mime_types` に示された形式を使用してください。一覧がない場合はモデルの入力要件を確認してください。
400	`invalid_media_data`	`The media data is invalid. Provide valid media data.`	base64 の破損や data URI の構造不正など、メディアデータが無効であることが確認されています。データの完全性とエンコードを確認し、有効なメディアを指定してください。
400	`media_url_unreachable`	`The media URL could not be accessed. Make sure it is publicly accessible and returns valid media data.`	メディアのリンクにアクセスできないか、読み取れません。リンクが有効で、インターネットからアクセスでき、有効なメディアを返すことを確認してください。
400	`invalid_media`	`The media input could not be processed. Check that its data or URL is valid and uses a supported format.`	メディア入力を処理できず、具体的な原因は確認できていません。データや URL が有効で、モデルが対応する形式であることを確認してください。
413	`image_too_large`	`The image is too large. Reduce the image size to {max_bytes} bytes or less and try again.`	画像タスクのメディアが現在の処理上限を超えています。`error.details.max_bytes` またはエラーで示された上限に合わせてサイズを縮小し、再試行してください。
413	`request_too_large`	`The request body exceeds the 32 MiB limit. Reduce the request size and try again.`	HTTP リクエスト本文全体が 32 MiB を超えています。テキスト、パラメータ、インラインのエンコード済みメディアを含む送信内容を縮小してください。

サイズ制限

メディアサイズ：画像タスクで上限を超えると image_too_large が返されます。具体的な上限はエラーメッセージまたは error.details.max_bytes を確認してください。
リクエスト全体のサイズ：request_too_large は、テキスト、パラメータ、インラインのエンコード済みメディアを含む HTTP 本文が 32 MiB を超えたことを示します。URL のみを送信する場合、リンク自体が本文に含まれます。リンク先のファイルには引き続きモデルのメディア制限が適用されます。
実際のサイズ：error.details.actual_bytes は全体のサイズが確認できた場合にのみ含まれます。URL からの読み取りが上限に達して停止した場合、このフィールドが省略されることがあります。

対応形式 選択したモデルによって異なります。まず error.details.allowed_mime_types またはエラーメッセージの形式一覧を確認してください。一覧がない場合はモデルの Schema を参照してください。 メッセージ内のプレースホルダー

{media_kind}：実際のメディアの種類。種類が確認できている場合、invalid_media_data と media_url_unreachable のメッセージでも image または video が使われます。
{max_bytes}：バイト単位の上限。画像の上限が不明な場合は The image is too large. Reduce the image size and try again. が返されます。
{allowed_formats}：許可される形式の一覧。形式エラーのメッセージに Use one of: {allowed_formats}. が追加される場合があります。

生成リクエストと返された結果

HTTP	`code`	`message`	説明
502	`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then try again. If the problem persists, contact support with the request ID.`	モデルプロバイダーはリクエストを完了しましたが、利用可能な画像を返しませんでした。リクエストを調整するか別のモデルを選択して再試行してください。解決しない場合はリクエスト ID を添えてサポートに連絡してください。HTTP 502 だけを理由に無条件で生成を自動再実行しないでください。
422	`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	モデルプロバイダーが生成内容をブロックし、利用可能な画像を返しませんでした。プロンプトまたは入力内容を変更して再試行してください。今回の生成料金は発生しません。
400	`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	モデルプロバイダーがリクエストを拒否しました。このコードだけではコンテンツ違反と断定できません。パラメータと入力内容を確認し、修正して再試行してください。
502	`upstream_bad_response`	`The model provider response could not be processed. Contact support with the request ID.`	モデルプロバイダーは応答しましたが、プラットフォームで処理できませんでした。生成結果が存在しないと確認されたわけではありません。リクエスト ID を添えてサポートに連絡し、パラメータエラーや空の結果と自己判断しないでください。
400	`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao が実在人物の画像に関する特定のプライバシー拒否コードを返しました。実在人物の認証を完了し、有効化済みの `asset://` 素材を使用してください。実在人物の素材に関するドキュメントをご覧ください。
504	`sync_timeout`	`Generation did not complete within the waiting period. Contact support with the request ID.`	待機時間内に生成が完了しませんでした。タイムアウトはリクエストが実行されなかったことを証明しません。リクエスト ID を添えてサポートに連絡してください。返されていないタスク ID を照会しないでください。
502	`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID or request ID.`	タスクはモデルプロバイダーに送信済みですが、その後の状態を確認できません。同じタスクを再送信しないでください。リクエスト ID と、取得済みであればタスク ID を添えてサポートに連絡してください。

アカウントと権限

HTTP	`code`	`message`	説明
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	API Key がないか無効です。`Authorization` ヘッダーと API Key を確認してください。
402	`insufficient_quota`	`Your account has insufficient quota. Add credits and try again.`	アカウントの利用枠が不足しています。クレジットを追加して再試行してください。
403	`permission_denied`	`You do not have permission to access this resource. Check the account, API key permissions, and IP restrictions.`	アカウントまたは API Key にアクセス権限がありません。アカウントの権限、API Key の権限、IP 制限を確認してください。
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to https://console.aihubmix.com/async-tasks to activate.`	アカウントで非同期タスクが有効になっていません。レスポンス内のコンソールリンクから有効化し、再試行してください。

サービスの可用性とレート制限

HTTP	`code`	`message`	説明
429	`rate_limited`	`Too many requests. Reduce the request rate and try again later.`	リクエスト頻度が高すぎます。頻度を下げて再試行してください。
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	モデルプロバイダーがレート制限を適用しています。時間をおいて再試行し、直後の繰り返し送信を避けてください。
500	`internal_error`	`An internal error occurred. Contact support with the request ID.`	プラットフォーム内部でエラーが発生しました。リクエスト ID を添えてサポートに連絡してください。有効な入力を繰り返し変更する必要はありません。
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	モデルプロバイダーが一時的に利用できません。接続失敗、プロバイダーのサービスエラー、応答の読み取り失敗などが考えられます。このコードだけでは結果の生成有無を確認できません。解決しない場合はリクエスト ID を添えてサポートに連絡してください。
502	`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	モデルプロバイダーを利用できません。表はデフォルトのメッセージであり、実際の応答ではより具体的な案内が示される場合があります。エラーの種類は `code` で判断し、リクエスト ID を添えてサポートに連絡してください。
503	`model_unavailable`	`The requested model is temporarily unavailable. Try again later or choose another model. If the problem persists, contact support with the request ID.`	このモデルは一時的に利用できません。時間をおいて再試行するか、別のモデルを選択してください。解決しない場合はリクエスト ID を添えてサポートに連絡してください。
503	`service_unavailable`	`The service is temporarily unavailable. Try again later. If the problem persists, contact support with the request ID.`	サービスが一時的に利用できません。現在の操作を後で再試行してください。ダウンロードが失敗した場合はダウンロードを再試行し、再生成する必要はありません。

provider_unavailable は、モデルプロバイダーの障害が明確に確認されたことを示します。一般的な 429 や 4xx だけでは、利用枠、コンテンツ審査、パラメータの問題を特定できません。

タスクの照会と結果のダウンロード

HTTP	`code`	`message`	説明
404	`task_not_found`	`The task was not found.`	タスクが存在しないか、現在のアカウントに属していません。タスク ID を確認し、API Key がタスクを作成したアカウントに属することを確認してください。
404	`result_not_found`	`The result was not found.`	結果が存在しないか、読み取り権限がありません。タスク ID、結果 ID、API Key を確認してください。無効と判明した結果 ID が、タスクの実行中という理由で 409 に変わることはありません。
400	`invalid_cursor`	`The cursor is invalid or expired. Start a new list request.`	ページネーションカーソルが無効または期限切れです。`after` を外して最初のページから取得し、その一覧で返された新しいカーソルを使用してください。
400	`result_id_required`	`This task has multiple results. Specify result_id.`	タスクに複数の結果がありますが、`result_id` が指定されていません。タスク出力から結果を選び、対応する `result_id` を指定してください。
409	`result_not_ready`	`The result is not available yet. Check the task status before downloading.`	タスクは待機中または実行中で、結果の準備ができていません。状態の照会を続け、準備ができたらダウンロードしてください。再生成する必要はありません。
410	`artifact_expired`	`The result has expired and is no longer available. Submit a new generation request.`	結果の保存期間が終了しています。期限切れの結果はダウンロードできません。必要に応じて新しい生成リクエストを送信してください。
429	`too_many_downloads`	`Download limit exceeded for this result.`	ダウンロード回数の上限に達しました。保存済みの結果を確認してください。待機するだけではダウンロード回数が回復するとは限りません。

タスク実行の失敗

タスク作成後の生成失敗は status=failed とタスク内の error で示されます。照会が成功した場合の HTTP ステータスは 200 のままです。

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "status": "failed",
  "output": [],
  "error": {
    "code": "image_not_generated",
    "message": "The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task."
  }
}

Task `code`	`message`	説明
`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task.`	モデルプロバイダーはリクエストを完了しましたが、利用可能な画像を返しませんでした。リクエストを調整するか別のモデルを選び、新しいタスクを送信してください。無条件で生成を自動再実行しないでください。
`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	モデルプロバイダーが生成内容をブロックし、利用可能な画像を返しませんでした。プロンプトまたは入力内容を変更し、新しいタスクを送信してください。今回の生成料金は発生しません。
`output_policy_violation`	`Generated content was rejected by the content policy.`	生成内容がコンテンツ審査を通過しませんでした。プロンプトまたは入力内容を変更し、新しいタスクを送信してください。既存のコンテンツ審査に関する課金ルールが適用されます。過去の料金は請求記録で確認してください。
`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	モデルプロバイダーがリクエストを拒否しました。このコードだけではコンテンツ違反と断定できません。パラメータと入力内容を確認、修正し、新しいタスクを送信してください。
`upstream_bad_response`	`The model provider response could not be processed. Contact support with the task ID.`	プラットフォームがモデルプロバイダーの応答を処理できません。生成結果が存在しないと確認されたわけではありません。タスク ID を添えてサポートに連絡してください。
`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID.`	タスクはモデルプロバイダーに送信済みですが、その後の状態を確認できません。再送信せず、タスク ID を添えてサポートに連絡してください。
`result_delivery_failed`	`The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID.`	生成結果は存在しますが、保存または配信を完了できませんでした。自動で再生成しないでください。タスク ID を添えてサポートに連絡し、まず既存の結果を調査してください。
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	モデルプロバイダーがレート制限を適用しています。時間をおいて再試行し、直後の繰り返し送信を避けてください。
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	タスク実行中に、モデルプロバイダーへの接続失敗、プロバイダーのサービスエラー、応答の読み取り失敗が発生しました。このコードだけでは結果の生成有無を確認できません。解決しない場合はタスク ID を添えてサポートに連絡してください。
`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	モデルプロバイダーを利用できません。表はデフォルトのメッセージであり、実際の応答ではより具体的な案内が示される場合があります。エラーの種類は `code` で判断し、タスク ID を添えてサポートに連絡してください。
`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao が実在人物の画像に関する特定のプライバシー拒否コードを返しました。実在人物の認証を完了し、有効化済みの `asset://` 素材を使用してください。実在人物の素材に関するドキュメントをご覧ください。
`sync_timeout`	`Generation timed out. Contact support with the task ID.`	生成タスクがタイムアウトしました。タスク ID を添えてサポートに連絡してください。
`internal_error`	`An internal error occurred. Contact support with the task ID.`	プラットフォーム内部でエラーが発生しました。タスク ID を添えてサポートに連絡してください。有効な入力を繰り返し変更する必要はありません。

メディア入力エラーは失敗した Task にも含まれる場合があり、コードの意味は上の入力エラー表と同じです。この場合も照会成功時の HTTP ステータスは 200 です。サイズエラーの message は submit a new task. で終わり、メディアを縮小して新しいタスクを送信するよう案内します。 output_blocked は、明確なブロックが発生し、利用可能な画像が返されなかったことを示します。今回の生成料金は発生しません。output_policy_violation には既存のコンテンツ審査に関する課金ルールが適用されます。過去の料金は請求記録で確認してください。

一覧の個別結果の読み取り失敗

画像・動画タスク一覧の一部の行に output_error が含まれる場合があります。

{
  "output_error": {
    "code": "internal_error",
    "type": "server_error",
    "message": "The task output could not be read. Contact support with the request ID.",
    "tid": "req_01K0ABCDEF"
  }
}

このフィールドは、今回その行の結果を読み取れなかったことを示します。一覧は HTTP 200 を返し、その行は output=[] になります。元の id、status、error とページネーションは変わらず、正常に読み取れる他のタスクに影響しません。status=completed でも output_error を確認し、結果を読み取れるか判断してください。 output_error.tid を添えてサポートに連絡してください。tid がない場合は今回のレスポンスヘッダーのリクエスト ID を提供できます。このエラーはタスクの状態や料金を変更せず、Webhook も発生させません。画像・動画の一覧では取得済みの expires_at が保持されます。統一 /ai/v1/tasks 一覧の読み取り失敗行は expires_at=null を返す場合がありますが、元の保存期間は引き続き適用されます。この処理は、個別の行の結果を読み取れず、利用できる代替手段がない場合に限ります。統一 tasks API で一覧全体の照会が失敗すると HTTP エラーが返され、詳細取得で同じ障害が起きた場合は HTTP 500 が返されます。関連ドキュメント：画像 API · 動画 API · 非同期タスク

完全な例

非同期タスクを作成し、ポーリングして、返された画像をすべて保存します。

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 を使用する方法

コールバックリクエスト

リトライと重複排除

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

HTTP 5xx エラーの報告

HTTP リクエストの失敗

リクエストパラメータとメディア入力

生成リクエストと返された結果

アカウントと権限

サービスの可用性とレート制限

タスクの照会と結果のダウンロード

タスク実行の失敗

一覧の個別結果の読み取り失敗

完全な例

​クイックスタート

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

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

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

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

​同期画像

​非同期画像

​画像の標準フィールド

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

​ステータスの説明

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

​メディア詳細の照会

​メディア一覧の照会

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

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

​画像のダウンロード

​Webhook を使用する方法

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

​リトライと重複排除

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

HTTP 5xx エラーの報告

​HTTP リクエストの失敗

​リクエストパラメータとメディア入力

​生成リクエストと返された結果

​アカウントと権限

​サービスの可用性とレート制限

​タスクの照会と結果のダウンロード

​タスク実行の失敗

​一覧の個別結果の読み取り失敗

​完全な例

クイックスタート

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

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

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

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

同期画像

非同期画像

画像の標準フィールド

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

ステータスの説明

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

メディア詳細の照会

メディア一覧の照会

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

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

画像のダウンロード

Webhook を使用する方法

コールバックリクエスト

リトライと重複排除

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

HTTP リクエストの失敗

リクエストパラメータとメディア入力

生成リクエストと返された結果

アカウントと権限

サービスの可用性とレート制限

タスクの照会と結果のダウンロード

タスク実行の失敗

一覧の個別結果の読み取り失敗

完全な例