画像

Create Image

指定されたプロンプトから画像を生成します

POST
/v1/images/generations

概要

GET /v1/models?recommended_for=image を使用して現在の画像モデルを取得し、選択した model を明示的に送信します。

各モデルは独自の操作とフィールドを受け付けます。GET /v1/models/{model}(モデルの取得)を実行すると、各操作のエンドポイントが tokenlab.request_format_summary.request_endpoint_by_operation に、各操作で受け付けられるフィールド、値、制限事項が tokenlab.request_format_details.operation_constraints に返されます。モデルがリストしていないフィールドを指定すると 400 unsupported_parameter が返される場合があります。誤ったエンドポイントに操作を送信すると 400 unsupported_endpoint が返されます。

画像タスクと結果:

  • サポートされているパラメータの中に async がリストされているモデルでは、最初にタスクを作成できます。async: true を送信し、その後 GET /v1/tasks/{id} をポーリングします。
  • 画像リンクは30日間保存されます。データ保持を参照してください。
  • タイムアウト後に作成リクエストを安全に再試行するには、Idempotency-Key ヘッダーを送信します。アイデムポテンシーキーを使用した安全な再試行を参照してください。

gpt-image-2 はトークン単位で課金される GPT Image モデルです。TokenLab は、テキスト入力、画像入力、レポートされたキャッシュ入力、画像出力トークンについて OpenAI 公式の使用量内訳に従っており、画像単位の固定料金モデルとしては請求されません。

gpt-image-2 の画像生成でサポートされているパブリックパラメータは、prompt、n、size、quality、response_format、async、background、output_format、output_compression または compression、moderation、および user です。background は auto または opaque を受け付けます。transparent はサポートされていません。size または quality を省略すると、TokenLab は auto を使用します。カスタムの size 値は、以下に記載されている柔軟な WIDTHxHEIGHT 規約に従う必要があります。

input_fidelity は、現在の TokenLab でサポートされている gpt-image-2 向けフィールドには含まれていません。省略しない場合、リクエストは 400 unsupported_parameter を返します。

SVGおよびGIF出力

gpt-image-2.6-flare および gpt-image-2.6-sunburst は、ラスター画像の代わりにSVGまたはアニメーションGIFを返すことができます。他のモデルではこれらの形式は拒否されます。

  • SVG: output_format: "svg" および svg: {"model": "..."} を送信します。画像モデルが最初に参照画像を描画し、次にオーサーモデルがそれに基づいてSVGを作成します。svg.model は必須です。モデルの詳細リストの parameter_options (svg.model) に受け入れ可能な値が記載されています。また、svg.reasoning.effort を送信することも可能です。SVGはこのエンドポイントでのみ機能し、n: 1 を指定する必要があり、partial_images や output_compression は使用できません。
  • GIF: output_format: "gif" を送信します。frame_count(2〜16、デフォルトは9)でフレーム数を設定し、frame_duration_ms(20〜2000、デフォルトは200)で各フレームの時間を設定します。size は1フレームあたりのサイズです。GIFでは partial_images や output_compression は使用できません。

結果は他の画像と同様に data[].b64_json または data[].url に格納されます。SVGはUTF-8 XMLテキストとしてデコードして .svg として保存し、GIFは .gif として保存してください。

課金: 画像トークンはモデルのトークン価格で課金され、GIFのフレームは画像出力トークンとして扱われます。SVGリクエストではオーサーモデルのトークンも課金され、その詳細はレスポンスの svg_usage に報告されます。料金はモデルページに記載されているSVG作成価格に基づきます。

モデルの動作に関する注意事項

Google Gemini 画像ファミリーのモデルは、同一のセレクター規約を共有していません:

  • gemini-3.1-flash-image、gemini-nano-banana-2.1、gemini-3-pro-image、nano-banana-2.1、および nano-banana-pro は、公開されている text-to-image、image-to-image、および image-edit 操作において、aspect_ratio に加えて resolution(1k、2k、4k)をサポートしています。
  • nano-banana-2 は、text-to-image と image-to-image の両方の生成で aspect_ratio および resolution(1k、2k、4k)をサポートしています。
  • gemini-3.1-flash-lite-image および nano-banana-2-lite は、1k 解像度のみで text-to-image、image-to-image、および image-edit をサポートしています。
  • nano-banana は aspect_ratio をサポートしていますが、パブリックな resolution の選択肢は公開していません。
  • gemini-3.1-flash-image、gemini-nano-banana-2.1、gemini-3.1-flash-lite-image、または gemini-3-pro-image で image-to-image を行う場合は、このエンドポイントで operation: "image-to-image" と参照画像を使用してください。これらのモデルの image-edit リクエストは /v1/images/edits に送信してください。
  • Nano Banana の参照画像リクエストには、このエンドポイント(/v1/images/generations)で nano-banana-2、nano-banana-2.1、nano-banana-2-lite、または nano-banana-pro を使用し、operation: "image-to-image" および image_urls を指定します。nano-banana-2、nano-banana-2.1、nano-banana-2-lite、および nano-banana-pro の image-edit リクエストも、このエンドポイントで operation: "image-edit" を使用します。Nano Banana の参照画像リクエストを /v1/images/edits に送信しないでください。
  • このエンドポイントでの参照画像は、JSON の image_url / image_urls、またはマルチパートの image ファイルとして指定できます。images[] および file_id は /v1/images/generations では受け付けられません。/v1/files の参照は、images[].file_id がドキュメントに記載されている /v1/images/edits モデルに対してのみ作成してください。

Google 画像ファミリーでは、aspect_ratio の使用を優先し、モデルが明示的にサポートしている場合にのみ resolution を送信してください。

xAI Grok Imagine 画像モデル(grok-imagine-image および grok-imagine-image-2.0)は、aspect_ratio に加えて resolution(1k、2k)をサポートしています。text-to-image はこのエンドポイントを使用します。これらの image-to-image および image-edit リクエストは /v1/images/edits を使用します。

hy-image-v3.5-preview は、このエンドポイントでテキストから1リクエストあたり1つの1024x1024画像を生成し、response_format: "url" のみをサポートします。参照画像の編集は /v1/images/edits で行います。

リクエストボディ

同期リクエストのタイムアウト: 一部の画像リクエストでは、生成が完了するのを待って最終的な画像をインラインで返します。高解像度または高品質のリクエストは1分近く、あるいはそれ以上かかる場合があるため、HTTPクライアントのタイムアウトは少なくとも 120s に設定してください。作成レスポンスに status: "pending"、task_id、または poll_url が含まれている場合は、代わりに GET /v1/tasks/{task_id} をポーリングしてください。

modelstring必須

使用するモデル(例:gpt-image-2、flux-pro-1.1、または nano-banana-pro)。現在の推奨リストを取得するには GET /v1/models?recommended_for=image をクエリしてください。

promptstring必須

希望する画像の説明テキスト(最大32,000文字)。詳細情報に prompt がリストされているすべてのモデルで必須です。

operationstring

text-to-image、image-to-image、または image-edit。省略した場合、リクエストに参照画像があれば image-to-image、それ以外は text-to-image になります。nano-banana-pro など、編集操作がこのエンドポイントにあるモデルの場合は image-edit を設定します。参照画像を含む text-to-image は 400 invalid_parameter を返します。

image_urlstring

image-to-image 生成用のパブリック画像URL。Nano Banana の参照画像リクエストの場合は、operation を image-to-image に設定します。nano-banana-pro には resolution を含めることができます。

image_urlsstring[]

パブリック参照画像URL(最大16個)。JSONリクエストで1つ以上の参照画像を指定する場合に使用します。このエンドポイントでは file_id および images[] はサポートされていません。

reference_image_urlsstring[]

プライマリ入力と参照画像を区別するモデル向けの、追加の参照画像URL(最大16個)。

imagefile

image-to-image 生成用のマルチパート参照画像ファイル。ソース画像がプライベートである場合や、ヘッダーによる保護が設定されている場合に使用します。これは、このエンドポイントで受け付けられない /v1/files の file_id とは異なります。

nintegerデフォルト: 1

生成する画像の枚数(モデルによって異なり、1〜10)。

sizestring

画像のサイズ。OpenAI形式の画像ファミリーや、正確なピクセルサイズを受け付けるその他のモデルに使用します。

gpt-image-2 の場合、size は auto または WIDTHxHEIGHT を受け付けます。カスタムの寸法は、両方とも16の倍数である必要があり、最も長い辺は最大 3840px、長辺と短辺の比率は最大 3:1、合計ピクセル数は 655,360 から 8,294,400 の間でなければなりません。gpt-image-2 の現在の TokenLab モデル詳細情報には、aspect_ratio および resolution は含まれていません。

解像度ティアを持つ Google 画像モデル(gemini-3.1-flash-image、gemini-nano-banana-2.1、gemini-3-pro-image、gemini-3.1-flash-lite-image、nano-banana-2、nano-banana-2.1、および nano-banana-pro)の場合、size はモデルのサイズテーブルにある出力サイズ(1Kでの16:9である 1376x768 など)または解像度ティア(1K、2K、4K)を受け付けます。TokenLab はティアを resolution として送信するため、リクエストとその料金は resolution を使用した場合と同じになります。モデルがサポートしていないティア(例:gemini-3.1-flash-lite-image での 2K)、または resolution と異なるティアを指定すると、エラーコード invalid_image_size_contract およびモデルの allowed_resolutions を伴う 400 が返されます。これらのモデルでは、aspect_ratio と resolution を組み合わせた形式が推奨されます。

aspect_ratiostring

モデル依存のアスペクト比セレクター。

Google 画像ファミリーで一般的な値には、1:1、16:9、9:16、3:2、および 2:3 があります。

resolutionstring

モデル依存の出力解像度。gemini-3.1-flash-image、gemini-nano-banana-2.1、gemini-3-pro-image、nano-banana-2、nano-banana-2.1、および nano-banana-pro は 1k、2k、4k をサポートしています。Grok Imagine 画像モデルは 1k と 2k をサポートしています。選択したモデルおよび操作で明示的にサポートされていない限り、このフィールドは省略してください。

qualitystring

画像の品質。gpt-image-2 などの GPT Image モデルでは、auto、low、medium、または high を使用します。その他のモデルでは異なる値を使用する場合があります。デフォルト以外の値を送信する前にモデルの詳細情報を確認してください。

output_formatstring

画像のファイル形式:png、jpeg、またはwebp。gpt-image-2.6-flareおよびgpt-image-2.6-sunburstではsvgおよびgifも指定可能です。詳細はSVG and GIF outputを参照してください。

svgobject

SVG設定。output_format: "svg"の場合のみ有効です。model(必須)はSVGを記述するオーサーモデルを選択します。reasoning.effortはオプションで推論の労力を設定します。

frame_countintegerデフォルト: 9

GIFのフレーム数。2から16の間で指定します。output_format: "gif"の場合のみ有効です。

frame_duration_msintegerデフォルト: 200

各GIFフレームの表示時間(ミリ秒)。20から2000の間で指定します。output_format: "gif"の場合のみ有効です。

response_formatstring

画像の返却形式:url または b64_json。

  • 省略時:モデルが画像バイトを返す場合、各画像は data[].b64_json に格納され、TokenLab が保存した場合は data[].url にも格納されます。モデルがリンクを返す場合、各画像は data[].url に格納されます。
  • url:各画像は data[].url にのみ格納されます。
  • b64_json:各画像は Base64 データとして data[].b64_json にのみ格納されます。

リンクは TokenLab メディア結果URLです。30日間有効です。データ保持を参照してください。

asyncbooleanデフォルト: false

true に設定すると、最初にタスクを作成します。サポートされているパラメータとして async をリストしているモデルのみがこれを受け入れます。例として gpt-image-2、flux-pro-1.1、nano-banana-pro、seedream-5.0-lite が挙げられます。その他のモデルでは、リクエストは 400 unsupported_async_mode を返します。完了した非同期画像タスクは、要求された response_format にかかわらずURLを返します。b64_json が必要な場合は同期リクエストを使用してください。

stylestring

オプションのスタイルセレクター。選択したモデルで明示的にドキュメントに記載されている場合にのみ送信してください。モデルメタデータに特に記載がない限り、gpt-image-2 では省略してください。

userstring

エンドユーザーの一意の識別子。

一部のモデルは、negative_prompt、seed、width、height、steps、guidance_scale、mask_url などのフィールドも受け付けます。これらはモデルの詳細情報にリストされている場合にのみ送信してください。stream: true はサポートされておらず、400 unsupported_parameter を返します。

レスポンス

インラインレスポンス

createdinteger

作成時の Unix タイムスタンプ。

dataarray

生成された画像の配列。

各オブジェクトには以下が含まれます:

  • url(string):画像の TokenLab メディア結果URL(30日間有効)。response_format が b64_json の場合は含まれません。response_format が省略されている場合、TokenLab が画像を保存できなかったときは存在しません。
  • b64_json(string):Base64画像データ。response_format が b64_json の場合、または省略されていてモデルが画像バイトを返す場合に存在します。
  • revised_prompt(string):選択したモデルがプロンプトの修正版を返した場合の、オプションのプロンプト修正内容
usageobject

利用可能な場合、gpt-image-2 などのトークン課金モデルのトークン数(input_tokens、output_tokens、total_tokens、およびその詳細)。

svg_usageobject

SVG authorモデルのトークン数(model、input_tokens、output_tokens、reasoning_tokens、total_tokens)。SVG出力の場合のみ存在します。これらのトークンは usage には含まれず、SVG作成料金が適用されます。

非同期タスクレスポンス

作成リクエスト内で最終的な画像を待つ代わりにタスクを作成するには、サポートしているモデルで async: true を設定します。レスポンスには status: "pending"、task_id、および poll_url が含まれます。タスクが completed または failed に達するまで /v1/tasks/{task_id} をポーリングしてください。

非同期画像タスクは最終的な画像URLのみを返します。生の b64_json 画像データが必要な場合は、同期リクエストを使用してください。

タスク作成時に、請求システムにより見積もり金額が仮確保される場合があります。完了したタスクには実際の使用量に基づいて課金され、失敗またはタイムアウトしたタスクは解放または返金されます。

createdinteger

作成時の Unix タイムスタンプ。

task_idstring

ポーリング用の一意のタスク識別子。

statusstring

初期ステータス:pending。

poll_urlstring

結果をポーリングするための相対URL(例:/v1/tasks/{id})。

dataarray

タスクが保留中(pending)の間は空です。完了した画像タスクは、生成された画像URLを data[].url に返します。

status: "pending" を受け取ったら、GET /v1/tasks/{task_id} を呼び出して結果を取得します。

リクエスト

cURL
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"
  }'
Python
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",
    extra_body={"aspect_ratio": "16:9", "resolution": "2k"}
)

print(response.data[0].url)
JavaScript
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'
});

console.log(response.data[0].url);
PHP
<?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'
    ])
]);

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

$data = json_decode($response, true);
echo $data['data'][0]['url'];

比率のみを指定する画像ファミリーの例:nano-banana の場合、aspect_ratio を送信し、resolution は省略します:

{
  "model": "nano-banana",
  "prompt": "A clean editorial product shot of a citrus soda can",
  "aspect_ratio": "16:9"
}

Nano Banana Pro 参照画像の例:リクエストは /v1/images/edits ではなく /v1/images/generations に送信してください。resolution はオプションであり、1k、2k、または 4k に設定できます:

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

プライベートまたはローカルのソース画像に対する直接マルチパートアップロードの例。/v1/images/generations に file_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..."
    }
  ]
}

エラー

リクエストエラーは 400(サイズ超過のアップロードの場合は 413)を返し、error.code が含まれます。画像リクエストで一般的なコードは以下のとおりです:

コード原因
unsupported_parameterモデルがそのフィールドをリストしていないか、stream が true になっています
unsupported_operationモデルに該当する operation がありません
unsupported_endpointこのモデルに対する操作は、/v1/images/edits などの別のエンドポイントにあります
unsupported_async_modeモデルが async: true をサポートしていません
invalid_resolution、invalid_aspect_ratio、invalid_parameter_value、too_many_items値がモデルの許容範囲外です。エラーには受け入れ可能な値が明記されます
invalid_image_size_contractモデルがサポートしていない size またはティア、あるいは resolution と競合する指定です
prompt_too_longプロンプトがモデルの許容長を超えています
request_too_large、file_too_largeアップロードがサイズ制限(1ファイルあたり 50 MiB、すべての入力合計で 200 MiB)を超えています

残高(402)、レート制限(429)、および再試行ルールについては、エラーハンドリングを参照してください。

モデルの選択

現在の利用状況、機能、および価格については、GET /v1/models?recommended_for=image をクエリするか、モデルページを確認してください。

モデルが常に同期的である、または常に非同期的であるとハードコーディングしないでください。async: true を指定しないリクエストであっても status: "pending" が返される場合があります。作成レスポンスに status: "pending" または status: "processing" が含まれている場合は、完了するまで常に GET /v1/tasks/{task_id} をポーリングしてください。

タスクベースのレスポンスの処理

画像モデルでは、レスポンスに status: "pending" / status: "processing" が含まれているかどうかを常に確認してください:

import requests
import time

def generate_image(prompt, model="gpt-image-2"):
    # 画像リクエストの作成
    response = requests.post(
        "https://api.tokenlab.sh/v1/images/generations",
        headers={"Authorization": "Bearer sk-your-api-key"},
        json={"model": model, "prompt": prompt, "async": True},
        timeout=120
    )
    response.raise_for_status()
    data = response.json()

    # タスクベースであるか確認
    if data.get("status") in ("pending", "processing"):
        task_id = data["task_id"]
        print(f"Image task started: {task_id}")

        # 結果をポーリング
        deadline = time.time() + 600
        while time.time() < deadline:
            status_resp = requests.get(
                f"https://api.tokenlab.sh/v1/tasks/{task_id}",
                headers={"Authorization": "Bearer sk-your-api-key"},
                timeout=30
            )
            status_resp.raise_for_status()
            status_data = status_resp.json()

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

            time.sleep(3)
        raise TimeoutError(f"Image task {task_id} did not finish in time")
    else:
        # インラインレスポンス
        return data["data"][0]["url"]

# 使用方法
url = generate_image("a beautiful sunset over mountains", model="gpt-image-2")
print(f"Generated image: {url}")

Hy Image 3.5 Preview の例。size は 1024x1024、n は 1 のみを受け付けます:

{
  "model": "hy-image-v3.5-preview",
  "prompt": "A yellow lemon on a white table",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}

認証

BearerAuth
AuthorizationBearer <token>

APIキー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。

場所: header

ヘッダー

X-TokenLab-Delivery-Policy?string

リクエストごとの配信ポリシー。APIキーおよびWorkspaceのデフォルト設定を上書きします。自動的にまず TokenLab Verified を試行し、出力、リクエストの受け入れ、または永続的なリソース作成の前に、一度だけ Official に切り替える場合があります。

指定できる値

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

リクエストによってタスクが作成された場合に、画像リクエストを安全に再試行するためのオプションのキー。リクエストごとに新しい一意の値(UUIDなど)を送信してください。同じキーとボディで再試行すると、そのタスクが返され、2つ目のタスクの作成、ディスパッチ、課金は行われません。画像を直接返すリクエストの場合、同じキーでの再試行は画像ではなくタスクステータス、または409とidempotent_response_not_replayableを返すことがあります。すでに受け入れられたキーで異なるボディを指定すると拒否されますが、その場合のステータスコードとエラーコードは保証されません。255文字を超えるキーは無視され、そのリクエストには冪等性保護が適用されません。詳細は冪等性キーを使用した安全な再試行を参照してください。

長さ1 <= length <= 255

リクエストボディ

レスポンス

application/json

application/json

application/json

application/json

application/json

application/json

application/json