生成图片

概述Copy Anchor Link

通过 GET /v1/models?recommended_for=image 查看当前图片模型，并在请求中明确填写 model。

gpt-image-2 是按 token 计价的 GPT Image 模型。TokenLab 按 OpenAI 官方的用量拆分计费，包括文本输入、图片输入、已报告的缓存输入和图片输出 tokens；它不是固定每张收费的模型。

对于 gpt-image-2 图片生成，TokenLab 支持的公开参数有 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-2.0 以及 legacy grok-imagine-image-pro）支持 aspect_ratio 和 resolution（1k、2k）。grok-imagine-image-pro 会作为 grok-imagine-image-2.0 的兼容 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"):
    # Create image request
    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()

    # Check if task-based
    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}")

        # Poll for result
        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:
        # Inline response
        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"
}