跳转到主要内容

概述

对于 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 参考图请求请设置 operationimage-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。其他图片系列可能使用提供者特定取值;发送非默认值前请先查看所选模型的元数据。
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
可选风格选择器。只有所选模型明确文档化支持时才发送;除非模型元数据另有说明,否则不要给 gpt-image-2 发送该字段。
user
string
终端用户的唯一标识符。

响应

内联响应

created
integer
创建时的 Unix 时间戳。
data
array
生成的图像数组。每个对象包含:
  • url (string):生成的图像 URL
  • b64_json (string):Base64 编码的图像(如果请求)
  • revised_prompt (string): 所选模型返回的可选提示词改写结果

异步任务响应

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
用于轮询的唯一任务 ID。
status
string
初始状态:pending
poll_url
string
用于轮询结果的相对 URL,例如 /v1/tasks/{id}
data
array
任务处于 pending 状态时为空。图片任务完成后,生成图片的 URL 会出现在 data[].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-2内联或任务式按 token 计费的 GPT Image 模型,支持灵活尺寸
flux-pro通常是任务式写实、高质量
qwen-image-plus通常是任务式文本渲染和提示词遵循较强
nano-banana-pro通常是任务式参考图工作流和高分辨率输出
grok-imagine-image通常是任务式xAI 图片生成,支持比例和分辨率选择
ideogram-v3通常是任务式文本渲染较强
不要把某个模型硬编码为总是同步或总是异步。如果创建响应返回 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}")