メインコンテンツへスキップ

概要

コーディング agent の場合は、まず GET /v1/models?recommended_for=image で現在推奨される画像モデルの候補を見つけ、そのうえで選んだ model をこのエンドポイントに明示的に渡してください。 gpt-image-2 は token 単位で課金される GPT Image モデルです。TokenLab は OpenAI 公式の usage 内訳に従い、テキスト入力、画像入力、報告されたキャッシュ入力、画像出力 token を精算します。固定の画像単価モデルとしては扱いません。 gpt-image-2 の画像生成でサポートされる公開パラメーターは、promptnsizequalityresponse_formatasyncbackgroundoutput_formatoutput_compression または compressionmoderationuser です。size または quality を省略すると TokenLab は auto を使用します。カスタム size は下記の柔軟な WIDTHxHEIGHT 契約に従う必要があります。 input_fidelity は現在の TokenLab の gpt-image-2 支援欄位には含まれません。省略してください。送信すると 400 unsupported_parameter が返ります。

モデル動作メモ

Google Gemini の画像ファミリーは、同じセレクター契約を共有していません:
  • gemini-3.1-flash-imagegemini-3-pro-imagenano-banana-pro は、公開されているテキストから画像、画像編集/image-to-image 操作で aspect_ratioresolution1k2k4k)をサポートします。
  • nano-banana-2 は、現在の TokenLab 契約ではテキストから画像の生成でのみ aspect_ratioresolution1k2k4k)をサポートします。
  • gemini-2.5-flash-imagenano-banananano-banana-editaspect_ratio をサポートしますが、公開されている resolution の選択肢はありません。
  • Nano Banana の参照画像リクエストでは、このエンドポイント(/v1/images/generations)で nano-banana-edit または nano-banana-pro を使い、operation: "image-to-image"image_urls を送信してください。Nano Banana の参照画像リクエストを /v1/images/edits に送信しないでください。
  • Nano Banana の image-to-image リクエストでは、nano-banana-proresolution1k2k4k)を指定できます。nano-banana-edit では省略してください。nano-banananano-banana-2 は現在の対応値としてテキストから画像モデルです。
  • このエンドポイントの参照画像は、JSON の image_url / image_urls、または multipart の image ファイルとして渡せます。/v1/images/generations では images[]file_id は受け付けません。/v1/files の参照は、images[].file_id を明示的にサポートする /v1/images/edits モデルでのみ使用します。
Google の画像ファミリーでは aspect_ratio を優先し、モデルが明示的に対応している場合だけ resolution を送信してください。 xAI Grok Imagine 画像モデル(grok-imagine-imagegrok-imagine-image-quality、および legacy grok-imagine-image-pro)は aspect_ratioresolution1k2k)をサポートします。grok-imagine-image-progrok-imagine-image-quality の互換 ID として保持されます。

リクエストボディ

同期リクエストのタイムアウト: 一部の画像リクエストでは、生成完了まで待って最終画像をインラインで返します。高解像度または高品質のリクエストは 1 分前後、またはそれ以上かかることがあるため、HTTP クライアントのタイムアウトは少なくとも 120s に設定してください。作成レスポンスに status: "pending"task_id、または poll_url が含まれる場合は、返された poll_url をポーリングしてください。
model
string
必須
使用するモデル(例: gpt-image-2flux-proqwen-image-plusnano-banana-pro)。現在の推奨リストは GET /v1/models?recommended_for=image で確認してください。
prompt
string
必須
生成したい画像の説明テキスト。
image_url
string
image-to-image 生成に使う公開 HTTPS 参照画像 URL。Nano Banana の参照画像リクエストでは operationimage-to-image に設定してください。nano-banana-proresolution を指定でき、nano-banana-edit では省略してください。
image_urls
string[]
公開 HTTPS 参照画像 URL の配列。JSON リクエストで 1 枚以上の参照画像を渡す場合に使います。このエンドポイントでは file_idimages[] はサポートされません。
reference_image_urls
string[]
主入力画像と参照画像を区別するプロバイダー向けの、追加のモデル固有参照画像 URL。
image
file
image-to-image 生成用の multipart 参照画像ファイル。元画像が非公開、またはヘッダー認証を必要とする場合に使います。これは /v1/files の file_id とは異なり、このエンドポイントでは file_id は受け付けません。
n
integer
デフォルト:"1"
生成する画像の数(1-10、モデルに依存)。
size
string
デフォルト:"1024x1024"
画像サイズ。OpenAI 形式の画像ファミリーや、正確なピクセルサイズを受け付ける他のモデルで使用します。gpt-image-2 では、sizeauto または WIDTHxHEIGHT を受け付けます。カスタム寸法は両辺とも 16 の倍数、最長辺は 3840px 以下、長辺/短辺の比率は 3:1 以下、総ピクセル数は 655,360 から 8,294,400 の範囲である必要があります。aspect_ratioresolution は、現時点では TokenLab の gpt-image-2 対応状況には含まれません。Google Gemini 画像ファミリーでは、size は互換エイリアスとして扱われ、モデル公開の aspect_ratio 契約、および対応時の resolution 契約にマッピングされます。これらのモデルでは aspect_ratio を直接送信することを推奨します。
aspect_ratio
string
モデル依存のアスペクト比セレクタ。Google 画像ファミリーでよく使われる値には 1:116:99:163:22:3 があります。
resolution
string
モデル依存の出力解像度セレクタ。gemini-3.1-flash-imagegemini-3-pro-image ではテキストから画像と画像編集で、nano-banana-pro ではテキストから画像と image-to-image で、nano-banana-2 ではテキストから画像のみでサポートされます。一般的な値は 1k2k4k です。モデル側で明記されていない限り、アスペクト比のみの Gemini 画像ファミリーには送信しないでください。xAI Grok Imagine 画像モデルでは 1k または 2k を使用してください。
quality
string
デフォルト:"standard"
画像品質。gpt-image-2 などの GPT Image モデルは autolowmediumhigh を使用します。他の画像ファミリーではプロバイダー固有の値を使う場合があるため、非デフォルト値を送る前に選択したモデルのメタデータを確認してください。
response_format
string
デフォルト:"url"
レスポンス形式:url または b64_json。デフォルトは url です。Azure Official または Azure-compatible の gpt-image-2 リクエストでは、TokenLab は画像データを b64_json として受け取ります。url リクエストでは各画像を CDN にアップロードして data[].url を返します。CDN ストレージが利用できない、またはアップロードに失敗した場合は、Base64 レスポンスへ変換せずリクエストを失敗させます。b64_json では生の Base64 を返します。
async
boolean
デフォルト:"false"
gpt-image-2 または公式 FLUX/BFL 画像モデルで true にすると、まずタスクを作成します。完了した非同期画像タスクは、要求された response_format に関係なく URL を返します。b64_json が必要な場合は同期リクエストを使用してください。
style
string
任意のスタイル指定です。選択したモデルが明示的に文書化している場合のみ送信してください。モデルメタデータに別途記載がない限り、gpt-image-2 には送信しないでください。
user
string
エンドユーザーの一意識別子。

レスポンス

インラインレスポンス

created
integer
作成時のUnixタイムスタンプ。
data
array
生成された画像の配列。各オブジェクトに含まれるもの:
  • url (string): 生成された画像のURL
  • b64_json (string): Base64エンコードされた画像(リクエストされた場合)
  • revised_prompt (string): 上流モデルが返した任意のプロンプト修正版(提供者が返す場合のみ)

非同期タスクレスポンス

gpt-image-2 または公式 FLUX/BFL 画像モデルで async: true を指定すると、作成リクエスト内で最終画像を待たずにタスクを作成します。レスポンスには status: "pending"task_idpoll_url が含まれます。タスクが completed または failed になるまで /v1/tasks/{task_id} をポーリングしてください。 非同期画像タスクは最終画像の URL のみを返します。生の b64_json 画像データが必要な場合は、同期リクエストを使用してください。 タスク作成時に見積額が予約される場合があります。完了したタスクは実使用量で精算され、失敗またはタイムアウトしたタスクは予約が解放または返金されます。
created
integer
作成時刻の Unix タイムスタンプ。
task_id
string
ポーリング用の一意なタスク識別子。
status
string
初期ステータス: pending
poll_url
string
結果をポーリングするための相対URL。例: /v1/tasks/{id}
data
array
タスクが保留中の間は空です。完了した画像タスクは data[].url に生成された画像URLを返します。
status: "pending" を受け取ったら、poll_url または GET /v1/tasks/{task_id} を使用して結果を取得します。
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="A cinematic portrait of a white cat sitting on a rainy windowsill",
    aspect_ratio="16:9",
    resolution="2k",
    n=1
)

print(response.data[0].url)
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const response = await client.images.generate({
  model: 'gemini-3-pro-image',
  prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill',
  aspect_ratio: '16:9',
  resolution: '2k',
  n: 1
});

console.log(response.data[0].url);
<?php
$ch = curl_init('https://api.tokenlab.sh/v1/images/generations');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer sk-your-api-key'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'gemini-3-pro-image',
        'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill',
        'aspect_ratio' => '16:9',
        'resolution' => '2k',
        'n' => 1
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['data'][0]['url'];
アスペクト比のみの画像ファミリーの例: gemini-2.5-flash-imagenano-banana、または nano-banana-edit では、aspect_ratio を送信し、resolution は省略します:
{
  "model": "gemini-2.5-flash-image",
  "prompt": "A clean editorial product shot of a citrus soda can",
  "aspect_ratio": "16:9"
}
Nano Banana Pro の参照画像の例: リクエストは /v1/images/generations に送信し、/v1/images/edits には送信しません。resolution は任意で、1k2k4k を指定できます。
{
  "model": "nano-banana-pro",
  "prompt": "Create a clean cinematic character image based on the reference images",
  "operation": "image-to-image",
  "image_urls": ["https://example.com/reference-1.png"],
  "aspect_ratio": "1:1",
  "resolution": "2k"
}
非公開またはローカルの元画像は multipart で直接アップロードできます。/v1/images/generationsfile_id は渡さないでください:
curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=nano-banana-pro" \
  -F "prompt=Create a clean cinematic character image based on this reference" \
  -F "operation=image-to-image" \
  -F "image=@reference.png" \
  -F "aspect_ratio=1:1" \
  -F "resolution=2k"
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
    }
  ]
}
{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

利用可能なモデル

以下は現在の代表的なモデル例であり、固定カタログではありません。最新の提供状況と価格は GET /v1/models?recommended_for=image または Models ページで確認してください。
モデルタイプ特徴
gpt-image-2インラインまたはタスクベーストークン課金の GPT Image モデル、柔軟なサイズ指定
flux-pro多くの場合タスクベースフォトリアルで高品質
qwen-image-plus多くの場合タスクベーステキストレンダリングとプロンプト追従が強い
nano-banana-pro多くの場合タスクベース参照画像ワークフローと高解像度出力
grok-imagine-image多くの場合タスクベースxAI 画像生成、アスペクト比と解像度選択に対応
ideogram-v3多くの場合タスクベーステキストレンダリングが強い
モデルを常に同期または常に非同期としてハードコードしないでください。作成レスポンスが status: "pending" を返す場合は、poll_url に従って完了までポーリングしてください。

タスクベースレスポンスの扱い

画像モデルでは、レスポンスに status: "pending" が含まれるかを必ず確認してください。
import requests
import time

def generate_image(prompt, model="flux-pro"):
    response = requests.post(
        "https://api.tokenlab.sh/v1/images/generations",
        headers={"Authorization": "Bearer sk-your-api-key"},
        json={"model": model, "prompt": prompt}
    )
    data = response.json()

    if data.get("status") == "pending":
        task_id = data["task_id"]
        poll_url = data.get("poll_url")
        print(f"Image task started: {task_id}")

        while True:
            status_resp = requests.get(
                f"https://api.tokenlab.sh{poll_url}" if poll_url else f"https://api.tokenlab.sh/v1/tasks/{task_id}",
                headers={"Authorization": "Bearer sk-your-api-key"}
            )
            status_data = status_resp.json()

            if status_data["status"] == "completed":
                return status_data["data"][0]["url"]
            if status_data["status"] == "failed":
                raise Exception(status_data.get("error", "Generation failed"))

            time.sleep(3)

    return data["data"][0]["url"]

url = generate_image("a beautiful sunset over mountains", model="flux-pro")
print(f"Generated image: {url}")