画像生成

画像生成は、テキストプロンプト（任意で参照画像による誘導つき）を 1 枚以上の画像に変換します。4 つのファミリーにまたがる 10 のモデルが、1 つのリクエストスキーマと 1 組のエンドポイントを共有します。モデルは model フィールドで選びます。

呼び出し方は 3 通りあります。

• 同期 — POST /v1/images/generation は画像が完成するまでブロックし、モデルの生の出力（base64 画像データ）をレスポンスボディで返します。
• 非同期 — POST /v1/images/generation/async は即座に taskId を返します。ホスティングされた画像 URL は GET /v1/images/generation/tasks/{taskId} をポーリングして取得します。
• 先に見積もり — POST /v1/images/generation/estimate-credits は、何も消費せずにクレジットコストと、アカウントが生成可能かどうかを返します。

モデルを選ぶ

まず下の表でモデルを選び、次に各ファミリーのページで正確な制限、挙動の癖、サンプルを確認してください。

model を省略した場合のデフォルトは gpt-image-2 です。標準 10 種の比率は 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 で、極端な 4 種を除くすべてです。詳しいルールは アスペクト比 を参照してください。

呼び出しの流れ

リクエストパラメータ

これらのパラメータは POST /v1/images/generation、POST /v1/images/generation/async、POST /v1/images/generation/estimate-credits に適用されます。3 つのエンドポイントは 1 つのリクエストスキーマを共有します。

¹ provider は 2 つの生成エンドポイントでは必須、estimate-credits では任意です。 ² prompt は 2 つの生成エンドポイントでは必須です。estimate-credits では空でも省略しても構いません（入力トークンの見積もりにのみ影響します）。

アスペクト比

カタログ全体では 14 種の比率があります。10 種は標準で、ほとんどのモデルが受け付けます。4 種は極端で、受け付けるのは gemini-3.1-flash-image と seedream-5-0-pro だけです。

上のスキーマデフォルトで埋まらなかった場合、aspectRatio は次のように解決されます。

画像サイズ

imageConfig.imageSize は 1K、2K（デフォルト）、4K を受け付けます。クレジット消費はモデルとサイズによって異なります。

クレジットコストをハードコードしないでください。使用するモデル、サイズ、比率での正確な数値は estimate-credits を呼び出して取得してください。

参照画像

参照画像は生成を誘導します。各画像は URL（fileData）か base64（inlineData）のどちらか一方で渡し（両方は不可）、配列はモデルの上限内に収めてください。

スキーマ上、referenceImages はすべてのモデルで 14 件が上限です。それより厳しい上限を持つファミリーは、超過分を 400 と上限を示すメッセージで拒否します。fileData と inlineData のどちらでも受け付ける MIME タイプは image/png、image/jpeg、image/webp、image/heic、image/heif です。

3 つの画像エンドポイントが受け付ける JSON ボディは最大 25MB です。プラットフォームの既定値の 4 倍になっているのは、base64 の inlineData がその中に収まる必要があるからです。base64 化するとファイルサイズは約 3 分の 1 増えるため、インラインで渡す画像は元のバイト数の合計で 18MB 程度までに抑えるか、fileData で URL を渡してください。

画像を生成する（同期）

POST /v1/images/generation

画像を生成し、完成までブロックします。レスポンスボディはモデルの生の出力です。base64 画像データを含む JSON であり、標準の { code, message, data } エンベロープではありません。レスポンス形式 を参照してください。

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "An astronaut riding a horse on Mars, photorealistic",
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "16:9"
    }
  }'

const response = await fetch(
  'https://api.marswave.ai/openapi/v1/images/generation',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      provider: 'google',
      model: 'gemini-3-pro-image',
      prompt: 'An astronaut riding a horse on Mars, photorealistic',
      imageConfig: { imageSize: '2K', aspectRatio: '16:9' },
    }),
  },
)
const result = await response.json()
const image = result.candidates[0].content.parts[0].inlineData

import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/images/generation',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'provider': 'google',
        'model': 'gemini-3-pro-image',
        'prompt': 'An astronaut riding a horse on Mars, photorealistic',
        'imageConfig': {'imageSize': '2K', 'aspectRatio': '16:9'},
    },
)
result = response.json()
image = result['candidates'][0]['content']['parts'][0]['inlineData']

参照画像を使う

参照画像の扱いはどのエンドポイントでも同じです。画像がすでにホスティングされている場合は fileData を、バイト列が手元にある場合は inlineData を使います。

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "Redraw this character in a watercolor style",
    "referenceImages": [
      {
        "fileData": {
          "fileUri": "https://example.com/character.png",
          "mimeType": "image/png"
        }
      }
    ],
    "imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" }
  }'

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "Redraw this character in a watercolor style",
    "referenceImages": [
      {
        "inlineData": {
          "data": "'"$(base64 -w0 character.png)"'",
          "mimeType": "image/png"
        }
      }
    ],
    "imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" }
  }'

非同期生成

時間のかかるジョブや高解像度のジョブでは、リクエストを開いたままにせず、タスクを送信して結果をポーリングしてください。

非同期タスクを作成する

POST /v1/images/generation/async

リクエストボディは同期エンドポイントと同じです。即座に 202 と taskId を返します。生成はバックグラウンドで実行され、できあがった画像はホスティングされた URL として永続化されます。

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/async" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "An astronaut riding a horse on Mars, photorealistic",
    "imageConfig": { "imageSize": "4K", "aspectRatio": "16:9" }
  }'

レスポンス（202）：

{
  "code": 0,
  "message": "",
  "data": { "taskId": "65f0...", "status": "pending" }
}

タスクを取得する

GET /v1/images/generation/tasks/{taskId}

単一タスクのステータスと結果をポーリングします。status は pending、generating、success、fail のいずれかです。成功時は images にホスティングされた結果の URL が入ります。

curl "https://api.marswave.ai/openapi/v1/images/generation/tasks/65f0abc..." \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

{
  "code": 0,
  "message": "",
  "data": {
    "taskId": "65f0abc...",
    "status": "success",
    "images": [{ "url": "https://.../0.png", "mimeType": "image/png" }],
    "createdAt": 1750000000000,
    "completedAt": 1750000020000
  }
}

タスク一覧を取得する

GET /v1/images/generation/tasks

自分の画像タスクを新しい順に一覧します。

curl "https://api.marswave.ai/openapi/v1/images/generation/tasks?page=1&pageSize=20&status=success" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "taskId": "65f0...",
        "status": "success",
        "images": [],
        "createdAt": 1750000000000,
        "completedAt": 1750000020000
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}

クレジットの見積もり

POST /v1/images/generation/estimate-credits

指定した設定のクレジットコストと、アカウントの残高で足りるかどうかを返します。クレジットは消費せず、モデルも呼び出しません。ボディは生成エンドポイントと同じものを受け付け、ここでは provider と prompt が任意です。

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/estimate-credits" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "1:1"
    }
  }'

const response = await fetch(
  'https://api.marswave.ai/openapi/v1/images/generation/estimate-credits',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-image-2',
      imageConfig: { imageSize: '2K', aspectRatio: '1:1' },
    }),
  },
)
const { data } = await response.json()
console.log(data.credits, data.canGenerate)

import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/images/generation/estimate-credits',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'model': 'gpt-image-2',
        'imageConfig': {'imageSize': '2K', 'aspectRatio': '1:1'},
    },
)
data = response.json()['data']
print(data['credits'], data['canGenerate'])

見積もりレスポンス

標準エンベロープでラップされます。data オブジェクトは次のとおりです。

{
  "code": 0,
  "message": "",
  "data": {
    "model": "gpt-image-2",
    "imageSize": "2K",
    "aspectRatio": "1:1",
    "credits": 6,
    "canGenerate": true,
    "requiresSubscription": false,
    "pricing": { "pricingVersion": "gpt-image-2-lite-fixed-2026-06-15", "mode": "fixed" },
    "warnings": []
  }
}

無料生成枠

API キーからの呼び出しは、ListenHub アプリや Labnana アプリと同じアカウント単位の無料枠（freeUsages）残高を使います。新規登録、招待、チェックインで枠を獲得し、それを API 経由で消費します。現在の残高は GET /v1/user/subscription で取得し、その freeUsages マップを読んでください。

対応する残高が 0 より大きい場合、1K / 2K のリクエストはクレジットではなく無料生成を 1 回消費します。残高が 0 になると、同じリクエストは通常のクレジット課金にフォールバックします。

gemini-3-pro-image は、無料枠が独立した実行レーンで動き、分岐処理に使える独自の失敗メタデータを持つ唯一のモデルです。詳しくは Nano Banana → relax レーン を参照してください。

レスポンス形式

同期エンドポイントはモデルの生の出力をそのまま返します。成功時のボディには、生成された画像が base64 データとして含まれます。

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_ENCODED_IMAGE>"
            }
          }
        ]
      }
    }
  ]
}

data フィールドを base64 からデコードすると画像ファイルが得られます。非同期の経路では画像がこちらで永続化され、タスクオブジェクトにホスティングされた url が返るため、base64 のデコードは不要です。

エラーコード

エラーは標準エンベロープ（code が非ゼロ）で返ります。同期エンドポイントの場合は、無料生成枠 に記載した生のエラーボディで返ります。

2 つの生成エンドポイントには、ユーザー単位およびグローバルのレート制限がかかります。base64 の参照画像（inlineData）を含むリクエストには別の、より厳しい制限がかかり、ピーク時には最初に絞られることがあります。estimate-credits にはレート制限がありません。

コンテンツ審査

同期エラーオブジェクトと、タスク詳細・一覧内の失敗タスクには、任意の contentModeration が付く場合があります。審査による拒否が確認された場合にのみ返されます。code、status、message を含む既存のフィールドと値は変わりません。既存のエラー処理に加えて利用してください。

理由が空または不明の場合は、汎用の審査拒否メッセージを表示してください。プロバイダーのエラー原文ではなく、独自の短いローカライズ済み文言を使用します。メタデータの例：

{
  "contentModeration": {
    "rejected": true,
    "reasons": [],
    "stage": "unknown"
  }
}

プロンプトや参照画像の審査で生成が拒否された場合は contentModeration を使用します。生成は成功しても公開できない画像には、同じ構造の任意の publicationModeration が付く場合があります。stage は審査対象を保持し、プロンプトの制限は input、生成画像の制限は output、両方による制限は unknown です。公開制限によって生成失敗にはなりません。既存の成功ステータスと画像 URL は変わらず、閲覧とダウンロードには従来のアクセス条件が適用されます。「公開不可」と固定の理由を表示し、フィールドがない場合に制限を推測しないでください。

関連