Chuyển đến nội dung chính

Tổng quan

Dành cho coding agents, hãy khám phá shortlist hình ảnh được khuyến nghị hiện tại trước bằng GET /v1/models?recommended_for=image, rồi gửi rõ model đã chọn đến endpoint này. gpt-image-2 là model GPT Image tính phí theo token. TokenLab bám theo chi tiết usage chính thức của OpenAI để tính token đầu vào văn bản, đầu vào hình ảnh, đầu vào cache khi được báo cáo, và token đầu ra hình ảnh; model này không được tính như giá cố định cho mỗi ảnh. Với tạo ảnh bằng gpt-image-2, các tham số public được hỗ trợ gồm prompt, n, size, quality, response_format, async, background, output_format, output_compression hoặc compression, moderation, và user. Nếu bỏ qua size hoặc quality, TokenLab dùng auto; giá trị size tùy chỉnh phải theo hợp đồng linh hoạt WIDTHxHEIGHT được mô tả bên dưới. input_fidelity không nằm trong hợp đồng public hiện tại của TokenLab cho gpt-image-2; hãy bỏ trường này, nếu gửi request sẽ trả 400 unsupported_parameter.

Ghi chú hành vi mô hình

Google Gemini không dùng cùng một hợp đồng selector:
  • gemini-3.1-flash-image, gemini-3-pro-image, và nano-banana-pro hỗ trợ aspect_ratio cùng resolution (1k, 2k, 4k) cho các operation text-to-image và image-edit/image-to-image công khai.
  • nano-banana-2 chỉ hỗ trợ aspect_ratio cùng resolution (1k, 2k, 4k) cho text-to-image trong contract TokenLab hiện tại.
  • gemini-2.5-flash-image, nano-banana, và nano-banana-edit hỗ trợ aspect_ratio nhưng không công khai resolution.
  • Với request Nano Banana dùng ảnh tham chiếu, hãy dùng nano-banana-edit hoặc nano-banana-pro trên endpoint này (/v1/images/generations) với operation: "image-to-image"image_urls. Đừng gửi request ảnh tham chiếu Nano Banana tới /v1/images/edits.
  • Với request Nano Banana image-to-image, nano-banana-pro có thể gửi resolution (1k, 2k, 4k); nano-banana-edit phải bỏ qua trường này. nano-banananano-banana-2 là model text-to-image trong contract công khai hiện tại.
  • Ảnh tham chiếu trên endpoint này có thể gửi bằng JSON image_url / image_urls, hoặc file multipart image. /v1/images/generations không nhận images[] hay file_id; tham chiếu /v1/files chỉ dùng cho model /v1/images/edits có tài liệu rõ images[].file_id.
Với các model hình ảnh của Google, hãy ưu tiên aspect_ratio và chỉ gửi resolution khi model đó hỗ trợ rõ ràng. Các model hình ảnh xAI Grok Imagine (grok-imagine-image, grok-imagine-image-quality, và legacy grok-imagine-image-pro) hỗ trợ aspect_ratio cùng resolution (1k, 2k). grok-imagine-image-pro được giữ làm ID tương thích cho grok-imagine-image-quality.

Thân Yêu Cầu

Timeout cho yêu cầu đồng bộ: một số yêu cầu hình ảnh sẽ trả ảnh cuối cùng inline và chờ quá trình tạo hoàn tất. Yêu cầu độ phân giải cao hoặc chất lượng cao có thể mất gần một phút hoặc lâu hơn, vì vậy hãy đặt timeout của HTTP client ít nhất là 120s. Nếu phản hồi tạo có status: "pending", task_id, hoặc poll_url, hãy theo poll_url được trả về để polling.
model
string
bắt buộc
Model cần dùng (ví dụ: gpt-image-2, flux-pro, qwen-image-plus hoặc nano-banana-pro). Dùng GET /v1/models?recommended_for=image để lấy danh sách đề xuất hiện tại.
prompt
string
bắt buộc
Mô tả bằng văn bản cho hình ảnh mong muốn.
image_url
string
URL HTTPS công khai của ảnh tham chiếu cho image-to-image. Với request Nano Banana dùng ảnh tham chiếu, đặt operationimage-to-image; nano-banana-pro có thể gửi resolution, còn nano-banana-edit nên bỏ qua trường này.
image_urls
string[]
Danh sách URL HTTPS công khai của ảnh tham chiếu. Dùng khi request JSON cần một hoặc nhiều ảnh tham chiếu. Endpoint này không hỗ trợ file_idimages[].
reference_image_urls
string[]
URL ảnh tham chiếu bổ sung theo từng model, dành cho provider phân biệt ảnh đầu vào chính và ảnh tham chiếu.
image
file
File ảnh tham chiếu multipart cho image-to-image. Dùng khi ảnh nguồn là riêng tư hoặc cần header xác thực. Trường này khác với file_id của /v1/files; endpoint này không nhận file_id.
n
integer
mặc định:"1"
Số lượng hình ảnh cần tạo (1-10, tùy theo model).
size
string
mặc định:"1024x1024"
Kích thước ảnh. Dùng cho các dòng ảnh kiểu OpenAI và các model khác chấp nhận kích thước pixel chính xác.Với gpt-image-2, size chấp nhận auto hoặc WIDTHxHEIGHT. Kích thước tùy chỉnh phải có cả hai cạnh là bội số của 16, cạnh dài nhất không quá 3840px, tỷ lệ cạnh dài/cạnh ngắn không quá 3:1, và tổng số pixel nằm trong khoảng 655,360 đến 8,294,400. aspect_ratioresolution hiện không thuộc chi tiết model của TokenLab cho gpt-image-2.Với các dòng ảnh Google Gemini, size được xem là alias tương thích ánh xạ sang chi tiết model aspect_ratio của model và, khi được hỗ trợ, resolution. Với các model này, nên gửi trực tiếp aspect_ratio.
aspect_ratio
string
Bộ chọn tỷ lệ khung hình theo từng model.Các giá trị phổ biến của nhóm model hình ảnh Google gồm 1:1, 16:9, 9:16, 3:2, và 2:3.
resolution
string
Bộ chọn độ phân giải đầu ra theo từng model.Được hỗ trợ trên gemini-3.1-flash-imagegemini-3-pro-image cho text-to-image và image-edit, trên nano-banana-pro cho text-to-image và image-to-image, và trên nano-banana-2 chỉ cho text-to-image. Giá trị thường dùng là 1k, 2k, và 4k. Không gửi tham số này cho các model Gemini hình ảnh chỉ nhận tỷ lệ khung hình trừ khi tài liệu của model đó nói rõ. Với model hình ảnh xAI Grok Imagine, dùng 1k hoặc 2k.
quality
string
mặc định:"standard"
Chất lượng ảnh. Các model GPT Image như gpt-image-2 dùng auto, low, medium hoặc high. Các họ ảnh khác có thể dùng giá trị riêng của provider; hãy kiểm tra metadata của model trước khi gửi giá trị khác mặc định.
response_format
string
mặc định:"url"
Định dạng response: url hoặc b64_json. Mặc định là url.Với gpt-image-2 qua Azure Official hoặc dịch vụ tương thích Azure, TokenLab nhận kết quả ảnh dưới dạng b64_json. Với request url, TokenLab tải từng ảnh lên CDN rồi trả về data[].url. Nếu CDN storage không khả dụng hoặc upload thất bại, request sẽ thất bại và không chuyển thành response Base64. Với b64_json, Base64 gốc được trả về.
async
boolean
mặc định:"false"
Đặt true với gpt-image-2 hoặc các model hình ảnh FLUX/BFL chính thức để tạo task trước. Task ảnh async hoàn tất trả về URL bất kể response_format được yêu cầu; dùng request đồng bộ nếu cần b64_json.
style
string
Bộ chọn style tùy chọn. Chỉ gửi khi model đã chọn tài liệu hóa rõ ràng tham số này; bỏ qua với gpt-image-2 trừ khi metadata của model nói khác.
user
string
Một định danh duy nhất cho end-user.

Phản Hồi

Phản Hồi Đồng Bộ

created
integer
Unix timestamp của thời điểm tạo.
data
array
Mảng các hình ảnh được tạo.Mỗi object chứa:
  • url (string): URL của hình ảnh được tạo
  • b64_json (string): Hình ảnh mã hoá Base64 (nếu được yêu cầu)
  • revised_prompt (string): Bản sửa prompt tùy chọn khi model đã chọn trả về trường này

Phản hồi task async

Đặt async: true với gpt-image-2 hoặc các model hình ảnh FLUX/BFL chính thức để tạo task thay vì chờ ảnh cuối trong request tạo ảnh. Phản hồi gồm status: "pending", task_idpoll_url. Hãy poll /v1/tasks/{task_id} cho đến khi task chuyển sang completed hoặc failed. Task ảnh async chỉ trả về URL của ảnh cuối. Nếu cần dữ liệu ảnh thô b64_json, hãy dùng request đồng bộ. Khi tạo task, hệ thống có thể giữ trước chi phí ước tính. Task hoàn tất được tính theo mức dùng thực tế; task thất bại hoặc timeout sẽ giải phóng hoặc hoàn lại khoản giữ trước.
created
integer
Dấu thời gian Unix khi tạo.
task_id
string
Mã định danh tác vụ duy nhất để thăm dò.
status
string
Trạng thái ban đầu: pending.
poll_url
string
URL tương đối để thăm dò kết quả, ví dụ /v1/tasks/{id}.
data
array
Trống trong khi tác vụ đang chờ xử lý. Các tác vụ hình ảnh đã hoàn tất trả về các URL hình ảnh được tạo trong data[].url.
Khi bạn nhận được status: "pending", hãy dùng poll_url hoặc GET /v1/tasks/{task_id} để truy xuất kết quả.
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'];
Ví dụ cho dòng hình ảnh chỉ nhận tỷ lệ khung hình: với gemini-2.5-flash-image, nano-banana, hoặc nano-banana-edit, hãy gửi aspect_ratio nhưng bỏ qua resolution:
{
  "model": "gemini-2.5-flash-image",
  "prompt": "A clean editorial product shot of a citrus soda can",
  "aspect_ratio": "16:9"
}
Ví dụ Nano Banana Pro dùng ảnh tham chiếu: gửi request tới /v1/images/generations, không gửi tới /v1/images/edits. resolution là tùy chọn và có thể đặt là 1k, 2k, hoặc 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"
}
Với ảnh nguồn riêng tư hoặc trên máy local, hãy upload trực tiếp bằng multipart. Đừng gửi file_id tới /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": []
}

Model Khả Dụng

Đây là các ví dụ model hiện tại, không phải catalog cố định. Dùng GET /v1/models?recommended_for=image hoặc trang Models để xem khả dụng và giá mới nhất.
Mô hìnhLoạiTính năng
gpt-image-2Inline hoặc taskModel GPT Image tính giá theo token, kích thước linh hoạt
flux-proThường là taskPhotorealistic, chất lượng cao
qwen-image-plusThường là taskRender chữ và bám prompt tốt
nano-banana-proThường là taskWorkflow ảnh tham chiếu và đầu ra độ phân giải cao
grok-imagine-imageThường là taskTạo ảnh xAI với chọn tỉ lệ và độ phân giải
ideogram-v3Thường là taskRender chữ tốt
Đừng hard-code một model là luôn đồng bộ hay luôn bất đồng bộ. Nếu response tạo ra trả về status: "pending", hãy theo poll_url và polling đến khi hoàn tất.

Xử Lý Phản Hồi Dựa Trên Task

Với các model hình ảnh, luôn kiểm tra xem response có chứa status: "pending" hay không: