跳轉到主要內容

概覽

對於 coding agent,請先透過 GET /v1/models?recommended_for=image 找出目前推薦的圖片模型清單,然後把選定的 model 明確傳給這個端點。 gpt-image-2 是按 token 計費的 GPT Image 模型。TokenLab 依 OpenAI 官方 usage 明細結算文字輸入、圖片輸入、已回報的快取輸入與圖片輸出 token;它不是固定每張圖片計費的模型。 對於 gpt-image-2 圖像生成,公共參數支援 promptnsizequalityresponse_formatasyncbackgroundoutput_formatoutput_compressioncompressionmoderationuser。未傳 sizequality 時 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 在公開的文字生圖、圖片編輯/圖生圖操作中支援 aspect_ratioresolution1k2k4k)。
  • nano-banana-2 在目前 TokenLab 契約中僅文字生圖支援 aspect_ratioresolution1k2k4k)。
  • gemini-2.5-flash-imagenano-banananano-banana-edit 支援 aspect_ratio,但不提供公開的 resolution 選項。
  • Nano Banana 參考圖請求請在本端點(/v1/images/generations)使用 nano-banana-editnano-banana-pro,並傳送 operation: "image-to-image"image_urls。不要把 Nano Banana 參考圖請求送到 /v1/images/edits
  • Nano Banana 圖生圖請求中,nano-banana-pro 可以傳送 resolution1k2k4k);nano-banana-edit 必須省略此參數。nano-banananano-banana-2 在目前対応状況中是文字生圖模型。
  • 本端點的參考圖可以透過 JSON image_url / image_urls 傳入,也可以用 multipart image 檔案直接上傳。/v1/images/generations 不接受 images[]file_id;只有明確支援 images[].file_id/v1/images/edits 模型才使用 /v1/files 回傳的引用。
Google 圖片系列請優先使用 aspect_ratio,只有模型明確支援時才傳送 resolution xAI Grok Imagine 圖片模型(grok-imagine-imagegrok-imagine-image-quality 以及 legacy grok-imagine-image-pro)支援 aspect_ratioresolution1k2k)。grok-imagine-image-pro 會作為 grok-imagine-image-quality 的相容 ID 保留。

請求本文

同步請求逾時: 某些圖片請求會以内嵌方式返回最終圖片,並等待生成完成。高解析度或高品質請求可能接近一分鐘甚至更久,因此請將 HTTP 用戶端逾時設定為至少 120s。如果建立回應包含 status: "pending"task_idpoll_url,請改為依照返回的 poll_url 輪詢。
model
string
必填
要使用的模型(例如 gpt-image-2flux-proqwen-image-plusnano-banana-pro)。使用 GET /v1/models?recommended_for=image 取得目前推薦清單。
prompt
string
必填
所需圖片的文字描述。
image_url
string
用於圖生圖的公開 HTTPS 參考圖 URL。Nano Banana 參考圖請求請將 operation 設為 image-to-imagenano-banana-pro 可以傳送 resolutionnano-banana-edit 應省略此參數。
image_urls
string[]
公開 HTTPS 參考圖 URL 陣列。JSON 請求需要一張或多張參考圖時使用此欄位。本端點不支援 file_idimages[]
reference_image_urls
string[]
額外的模型特定參考圖 URL,用於區分主要輸入圖與參考圖的供應商。
image
file
用於圖生圖的 multipart 參考圖檔案。來源圖片是私有或需要請求標頭授權時,請使用直接上傳。這不同於 /v1/files 的 file_id;本端點不接受 file_id
n
integer
預設值:"1"
要產生的圖片數量(1-10,依模型而定)。
size
string
預設值:"1024x1024"
圖片尺寸。用於 OpenAI 風格的圖片系列,以及接受精確像素尺寸的其他模型。對於 gpt-image-2size 接受 autoWIDTHxHEIGHT。自訂寬高都必須是 16 的倍數,最長邊不超過 3840px,長邊/短邊比例不超過 3:1,總像素必須介於 655,3608,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 在文字生圖與圖生圖中支援;nano-banana-2 僅文字生圖支援。常見值為 1k2k4k。除非模型明確說明,否則不要傳給僅支援比例選擇的 Gemini 圖片系列。xAI Grok Imagine 圖片模型請使用 1k2k
quality
string
預設值:"standard"
圖片品質。gpt-image-2 等 GPT Image 模型使用 autolowmediumhigh。其他圖片系列可能使用提供者特定取值;傳送非預設值前請先查看所選模型的 metadata。
response_format
string
預設值:"url"
回應格式:urlb64_json,預設為 url對於 Azure Official 或 Azure-compatible 的 gpt-image-2 請求,TokenLab 會以 b64_json 接收圖片資料。請求 url 時,TokenLab 會把每張圖上傳到 CDN 並返回 data[].url。如果 CDN 儲存不可用或上傳失敗,請求會失敗,而不是改為 Base64 回應;請求 b64_json 時直接返回原始 Base64。
async
boolean
預設值:"false"
搭配 gpt-image-2 或官方 FLUX/BFL 圖像模型設為 true 時,會先建立任務。完成後的非同步圖片任務無論請求的 response_format 是什麼,都只返回 URL;如果需要 b64_json,請使用同步請求。
style
string
選填風格選擇器。只有所選模型明確文件化支援時才傳送;除非模型 metadata 另有說明,否則不要對 gpt-image-2 傳送此欄位。
user
string
終端使用者的唯一識別碼。

回應

即時回應

created
integer
建立時間的 Unix timestamp。
data
array
產生圖片的陣列。每個物件包含:
  • url(string):產生圖片的 URL
  • b64_json(string):Base64 編碼的圖片(若有要求)
  • revised_prompt (string): 所選模型回傳的選填 prompt 改寫結果

非同步任務回應

搭配 gpt-image-2 或官方 FLUX/BFL 圖像模型設定 async: true 後,建立請求會先返回任務,而不是等待最終圖片完成。回應包含 status: "pending"task_idpoll_url。請輪詢 /v1/tasks/{task_id},直到任務進入 completedfailed 非同步圖片任務最終只返回圖片 URL。如果你需要原始 b64_json 圖片資料,請使用同步請求。 任務建立時可能會先預留預估費用。任務完成後按實際用量結算;失敗或逾時的任務會釋放預留費用或退回費用。
created
integer
建立時間的 Unix 時間戳。
task_id
string
用於輪詢的唯一任務識別碼。
status
string
初始狀態:pending
poll_url
string
用於輪詢結果的相對 URL,例如 /v1/tasks/{id}
data
array
任務處於 pending 時為空。已完成的圖片任務會在 data[].url 中回傳產生的圖片 URL。
當你收到 status: "pending" 時,請使用 poll_urlGET /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-banananano-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/editsresolution 是選填參數,可設為 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 直接上傳。不要把 file_id 傳給 /v1/images/generations
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 或模型頁面。
模型類型特性
gpt-image-2Inline 或 task-based按 token 計費的 GPT Image 模型,支援彈性尺寸
flux-pro通常為 task-based寫實、高品質
qwen-image-plus通常為 task-based文字渲染與 prompt 遵循較強
nano-banana-pro通常為 task-based參考圖工作流與高解析度輸出
grok-imagine-image通常為 task-basedxAI 圖片生成,支援比例與解析度選擇
ideogram-v3通常為 task-based文字渲染較強
不要把模型硬編碼為永遠同步或永遠非同步。如果建立回應返回 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}")