TokenLab
取得 API Key
文件API 參考整合

圖像

建立圖片

根據 prompt 建立圖片

POST
/v1/images/generations

概覽

對於 coding agent，請先透過 GET /v1/models?recommended_for=image 找出目前推薦的圖片模型清單，然後把選定的 model 明確傳給這個端點。

gpt-image-2 是按 token 計費的 GPT Image 模型。TokenLab 依 OpenAI 官方 usage 明細結算文字輸入、圖片輸入、已回報的快取輸入與圖片輸出 token；它不是固定每張圖片計費的模型。

對於 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。

模型行為說明

Google Gemini 圖片系列不共用同一套選擇器契約：

  • gemini-3.1-flash-image、gemini-3-pro-image 和 nano-banana-pro 在公開的文字生圖、圖片編輯/圖生圖操作中支援 aspect_ratio 和 resolution（1k、2k、4k）。
  • nano-banana-2 在文字生圖與圖生圖中均支援 aspect_ratio 和 resolution（1k、2k、4k）。
  • gemini-2.5-flash-image、nano-banana 和 nano-banana-edit 支援 aspect_ratio，但不提供公開的 resolution 選項。
  • Nano Banana 參考圖請求請在本端點（/v1/images/generations）使用 nano-banana-edit 或 nano-banana-pro，並傳送 operation: "image-to-image" 與 image_urls。不要把 Nano Banana 參考圖請求送到 /v1/images/edits。
  • 本端點的參考圖可以透過 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-image、grok-imagine-image-quality 以及 legacy grok-imagine-image-pro）支援 aspect_ratio 與 resolution（1k、2k）。grok-imagine-image-pro 會作為 grok-imagine-image-quality 的相容 ID 保留。

請求本文

同步請求逾時： 某些圖片請求會以内嵌方式返回最終圖片，並等待生成完成。高解析度或高品質請求可能接近一分鐘甚至更久，因此請將 HTTP 用戶端逾時設定為至少 120s。如果建立回應包含 status: "pending"、task_id 或 poll_url，請改為依照返回的 poll_url 輪詢。

modelstring必填

要使用的模型（例如 gpt-image-2、flux-pro 或 nano-banana-pro）。使用 GET /v1/models?recommended_for=image 取得目前推薦清單。

promptstring必填

所需圖片的文字描述。

image_urlstring

用於圖生圖的公開 HTTPS 參考圖 URL。Nano Banana 參考圖請求請將 operation 設為 image-to-image；nano-banana-pro 可以傳送 resolution，nano-banana-edit 應省略此參數。

image_urlsstring[]

公開 HTTPS 參考圖 URL 陣列。JSON 請求需要一張或多張參考圖時使用此欄位。本端點不支援 file_id 和 images[]。

reference_image_urlsstring[]

額外的模型特定參考圖 URL，用於區分主要輸入圖與參考圖的供應商。

imagefile

用於圖生圖的 multipart 參考圖檔案。來源圖片是私有或需要請求標頭授權時，請使用直接上傳。這不同於 /v1/files 的 file_id；本端點不接受 file_id。

ninteger預設值: 1

要產生的圖片數量（1-10，依模型而定）。

sizestring

圖片尺寸。用於 OpenAI 風格的圖片系列，以及接受精確像素尺寸的其他模型。

對於 gpt-image-2，size 接受 auto 或 WIDTHxHEIGHT。自訂寬高都必須是 16 的倍數，最長邊不超過 3840px，長邊/短邊比例不超過 3:1，總像素必須介於 655,360 到 8,294,400 之間。aspect_ratio 與 resolution 目前不屬於 TokenLab 對 gpt-image-2 的対応状況。

對於 Google Gemini 圖片系列，size 會被視為相容別名，映射到模型公開的 aspect_ratio 契約，以及在支援時的 resolution 契約。建議對這些模型直接傳送 aspect_ratio。

aspect_ratiostring

依模型而定的長寬比選擇器。

Google 圖片系列常見值包括 1:1、16:9、9:16、3:2、2:3。

resolutionstring

輸出解析度取決於模型。gemini-3.1-flash-image、gemini-3-pro-image、nano-banana-2 和 nano-banana-pro 支援 1k、2k、4k；Grok Imagine 圖片模型支援 1k、2k。只有所選模型與操作明確支援時才傳送此欄位。

qualitystring

圖片品質。gpt-image-2 等 GPT Image 模型使用 auto、low、medium 或 high。其他圖片系列可能使用提供者特定取值；傳送非預設值前請先查看所選模型的 metadata。

response_formatstring預設值: url

回應格式：url 或 b64_json，預設為 url。

url 透過 data[].url 回傳圖片網址；b64_json 透過 data[].b64_json 回傳 Base64 圖片資料。

asyncboolean預設值: false

搭配 gpt-image-2 或官方 FLUX/BFL 圖像模型設為 true 時，會先建立任務。完成後的非同步圖片任務無論請求的 response_format 是什麼，都只返回 URL；如果需要 b64_json，請使用同步請求。

stylestring

選填風格選擇器。只有所選模型明確文件化支援時才傳送；除非模型 metadata 另有說明，否則不要對 gpt-image-2 傳送此欄位。

userstring

終端使用者的唯一識別碼。

回應

即時回應

createdinteger

建立時間的 Unix timestamp。

dataarray

產生圖片的陣列。

每個物件包含：

  • url（string）：產生圖片的 URL
  • b64_json（string）：Base64 編碼的圖片（若有要求）
  • revised_prompt (string): 所選模型回傳的選填 prompt 改寫結果

非同步任務回應

搭配 gpt-image-2 或官方 FLUX/BFL 圖像模型設定 async: true 後，建立請求會先返回任務，而不是等待最終圖片完成。回應包含 status: "pending"、task_id 和 poll_url。請輪詢 /v1/tasks/{task_id}，直到任務進入 completed 或 failed。

非同步圖片任務最終只返回圖片 URL。如果你需要原始 b64_json 圖片資料，請使用同步請求。

任務建立時可能會先預留預估費用。任務完成後按實際用量結算；失敗或逾時的任務會釋放預留費用或退回費用。

createdinteger

建立時間的 Unix 時間戳。

task_idstring

用於輪詢的唯一任務識別碼。

statusstring

初始狀態：pending。

poll_urlstring

用於輪詢結果的相對 URL，例如 /v1/tasks/{id}。

dataarray

任務處於 pending 時為空。已完成的圖片任務會在 data[].url 中回傳產生的圖片 URL。

當你收到 status: "pending" 時，請使用 poll_url 或 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'];

僅支援比例選擇的圖片系列範例：對於 gemini-2.5-flash-image、nano-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 是選填參數，可設為 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"
}

私有或本機來源圖片可以用 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..."
    }
  ]
}

可用模型

透過 GET /v1/models?recommended_for=image 查詢目前圖片模型、能力與價格。

不要把模型硬編碼為永遠同步或永遠非同步。如果建立回應返回 status: "pending"，請跟隨 poll_url 輪詢直到完成。

處理任務式回應

對於圖片模型，請一律檢查回應是否包含 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"]
        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"},
                timeout=30
            )
            status_resp.raise_for_status()
            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="gpt-image-2")
print(f"Generated image: {url}")

Hy Image 3.5 Preview 可根據文字生成 1024 像素方形圖像，並按文字指令編輯參考圖，適用於視覺草稿與構圖調整。

{
  "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 Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

位置: header

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified，並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。

可選值

  • "auto"
  • "verified"
  • "official"

請求主體

回應

application/json

application/json

application/json

application/json

application/json

application/json

application/json

取消批次

上一頁

編輯圖像

下一頁