建立圖片

概覽Copy Anchor Link

使用 GET /v1/models?recommended_for=image 獲取當前的圖片模型，然後明確發送所選的 model。

gpt-image-2 是一款按 Token 計費的 GPT Image 模型。TokenLab 遵循 OpenAI 官方的文字輸入、圖片輸入、已報告的快取輸入以及圖片輸出 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。

模型行為注意事項Copy Anchor Link

Google Gemini 圖片系列模型不共享相同的選擇器規範：

• gemini-3.1-flash-image、gemini-nano-banana-2.1、gemini-3-pro-image、nano-banana-2.1 和 nano-banana-pro 在其公開的文字轉圖片、圖片轉圖片和圖片編輯操作中支援 aspect_ratio 以及 resolution (1k、2k、4k)。
• nano-banana-2 在文字轉圖片和圖片轉圖片生成中均支援 aspect_ratio 和 resolution (1k、2k、4k)。
• gemini-3.1-flash-lite-image 和 nano-banana-2-lite 僅支援 1k 解析度的文字轉圖片、圖片轉圖片和圖片編輯。
• 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 進行圖片轉圖片操作，請使用此端點並設定 operation: "image-to-image" 以及參考圖片。請將這些模型的圖片編輯請求發送至 /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 的圖片編輯請求也使用此端點，並設定 operation: "image-edit"。請勿將 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 和舊版 grok-imagine-image-pro) 支援 aspect_ratio 以及 resolution (1k、2k)。grok-imagine-image-pro 作為 grok-imagine-image-quality 的相容性 ID 保留。

請求主體Copy Anchor Link

同步請求逾時： 部分圖片請求會內聯返回最終圖片並等待生成完成。高解析度或高品質請求可能需要接近一分鐘或更長時間，因此請將您的 HTTP 客戶端逾時設定為至少 120s。如果建立回應包含 status: "pending"、task_id 或 poll_url，請改為追蹤返回的 poll_url。

回應Copy Anchor Link

內聯回應Copy Anchor Link

非同步任務回應Copy Anchor Link

與 gpt-image-2 或官方 FLUX/BFL 圖片模型一起設定 async: true 以建立任務，而不是在建立請求中等待最終圖片。回應包含 status: "pending"、task_id 和 poll_url。請輪詢 /v1/tasks/{task_id} 直到任務達到 completed 或 failed。

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

計費可能會在任務建立時預留估算金額。已完成的任務按實際使用量計費，失敗或逾時的任務將釋放或退款。

當您收到 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"
  }'

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'];

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

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

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..."
    }
  ]
}

選擇模型Copy Anchor Link

查詢 GET /v1/models?recommended_for=image 或使用 模型頁面 以獲取當前的可用性、功能和價格。

請勿將模型硬編碼為始終同步或始終非同步。如果建立回應返回 status: "pending"，請追蹤 poll_url 並輪詢直到完成。

處理基於任務的回應Copy Anchor Link

對於圖片模型，請務必檢查回應是否包含 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"]
            elif status_data["status"] == "failed":
                raise Exception(status_data.get("error", "Generation failed"))

            time.sleep(3)
    else:
        # 內聯回應
        return data["data"][0]["url"]

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

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