画像
Create Image
指定されたプロンプトから画像を生成します
概要
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} をポーリングしてください。
使用するモデル(例:gpt-image-2、flux-pro-1.1、または nano-banana-pro)。現在の推奨リストを取得するには GET /v1/models?recommended_for=image をクエリしてください。
希望する画像の説明テキスト(最大32,000文字)。詳細情報に prompt がリストされているすべてのモデルで必須です。
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-to-image 生成用のパブリック画像URL。Nano Banana の参照画像リクエストの場合は、operation を image-to-image に設定します。nano-banana-pro には resolution を含めることができます。
パブリック参照画像URL(最大16個)。JSONリクエストで1つ以上の参照画像を指定する場合に使用します。このエンドポイントでは file_id および images[] はサポートされていません。
プライマリ入力と参照画像を区別するモデル向けの、追加の参照画像URL(最大16個)。
image-to-image 生成用のマルチパート参照画像ファイル。ソース画像がプライベートである場合や、ヘッダーによる保護が設定されている場合に使用します。これは、このエンドポイントで受け付けられない /v1/files の file_id とは異なります。
1生成する画像の枚数(モデルによって異なり、1〜10)。
画像のサイズ。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 を組み合わせた形式が推奨されます。
モデル依存のアスペクト比セレクター。
Google 画像ファミリーで一般的な値には、1:1、16:9、9:16、3:2、および 2:3 があります。
モデル依存の出力解像度。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 をサポートしています。選択したモデルおよび操作で明示的にサポートされていない限り、このフィールドは省略してください。
画像の品質。gpt-image-2 などの GPT Image モデルでは、auto、low、medium、または high を使用します。その他のモデルでは異なる値を使用する場合があります。デフォルト以外の値を送信する前にモデルの詳細情報を確認してください。
画像のファイル形式:png、jpeg、またはwebp。gpt-image-2.6-flareおよびgpt-image-2.6-sunburstではsvgおよびgifも指定可能です。詳細はSVG and GIF outputを参照してください。
SVG設定。output_format: "svg"の場合のみ有効です。model(必須)はSVGを記述するオーサーモデルを選択します。reasoning.effortはオプションで推論の労力を設定します。
9GIFのフレーム数。2から16の間で指定します。output_format: "gif"の場合のみ有効です。
200各GIFフレームの表示時間(ミリ秒)。20から2000の間で指定します。output_format: "gif"の場合のみ有効です。
画像の返却形式:url または b64_json。
- 省略時:モデルが画像バイトを返す場合、各画像は
data[].b64_jsonに格納され、TokenLab が保存した場合はdata[].urlにも格納されます。モデルがリンクを返す場合、各画像はdata[].urlに格納されます。 url:各画像はdata[].urlにのみ格納されます。b64_json:各画像は Base64 データとしてdata[].b64_jsonにのみ格納されます。
リンクは TokenLab メディア結果URLです。30日間有効です。データ保持を参照してください。
falsetrue に設定すると、最初にタスクを作成します。サポートされているパラメータとして async をリストしているモデルのみがこれを受け入れます。例として gpt-image-2、flux-pro-1.1、nano-banana-pro、seedream-5.0-lite が挙げられます。その他のモデルでは、リクエストは 400 unsupported_async_mode を返します。完了した非同期画像タスクは、要求された response_format にかかわらずURLを返します。b64_json が必要な場合は同期リクエストを使用してください。
オプションのスタイルセレクター。選択したモデルで明示的にドキュメントに記載されている場合にのみ送信してください。モデルメタデータに特に記載がない限り、gpt-image-2 では省略してください。
エンドユーザーの一意の識別子。
一部のモデルは、negative_prompt、seed、width、height、steps、guidance_scale、mask_url などのフィールドも受け付けます。これらはモデルの詳細情報にリストされている場合にのみ送信してください。stream: true はサポートされておらず、400 unsupported_parameter を返します。
レスポンス
インラインレスポンス
作成時の Unix タイムスタンプ。
生成された画像の配列。
各オブジェクトには以下が含まれます:
url(string):画像の TokenLab メディア結果URL(30日間有効)。response_formatがb64_jsonの場合は含まれません。response_formatが省略されている場合、TokenLab が画像を保存できなかったときは存在しません。b64_json(string):Base64画像データ。response_formatがb64_jsonの場合、または省略されていてモデルが画像バイトを返す場合に存在します。revised_prompt(string):選択したモデルがプロンプトの修正版を返した場合の、オプションのプロンプト修正内容
利用可能な場合、gpt-image-2 などのトークン課金モデルのトークン数(input_tokens、output_tokens、total_tokens、およびその詳細)。
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 画像データが必要な場合は、同期リクエストを使用してください。
タスク作成時に、請求システムにより見積もり金額が仮確保される場合があります。完了したタスクには実際の使用量に基づいて課金され、失敗またはタイムアウトしたタスクは解放または返金されます。
作成時の Unix タイムスタンプ。
ポーリング用の一意のタスク識別子。
初期ステータス:pending。
結果をポーリングするための相対URL(例:/v1/tasks/{id})。
タスクが保留中(pending)の間は空です。完了した画像タスクは、生成された画像URLを data[].url に返します。
status: "pending" を受け取ったら、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"
}'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)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
$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 APIキー認証。Dashboard > API > API KeysでAPIキーを作成または管理します。
場所: header
ヘッダー
リクエストごとの配信ポリシー。APIキーおよびWorkspaceのデフォルト設定を上書きします。自動的にまず TokenLab Verified を試行し、出力、リクエストの受け入れ、または永続的なリソース作成の前に、一度だけ Official に切り替える場合があります。
指定できる値
- "auto"
- "verified"
- "official"
リクエストによってタスクが作成された場合に、画像リクエストを安全に再試行するためのオプションのキー。リクエストごとに新しい一意の値(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