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

Documentation Index

Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
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, partial_images, 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. Ghi chu tuong thich: neu yeu cau gpt-image-2 gui input_fidelity, TokenLab se xoa truong nay truoc khi chuyen tiep vi GPT Image 2 tu dong xu ly dau vao hinh anh voi do trung thuc cao.

​
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-preview, gemini-3-pro-image-preview, nano-banana-2, và nano-banana-pro hỗ trợ aspect_ratio cùng resolution (1k, 2k, 4k) cho text-to-image.
  • gemini-2.5-flash-image, nano-banana, và nano-banana-edit hỗ trợ aspect_ratio nhưng không công khai resolution.
  • gemini-2.0-flash-preview-image-generation được tài liệu hoá ở đây như một mô hình text-to-image chỉ dùng prompt.
  • Với request ảnh tham chiếu cho nano-banana, nano-banana-2, và nano-banana-pro, hãy dùng endpoint này (/v1/images/generations) với operation: "image-to-image" và image_urls. Đừng gửi request ảnh tham chiếu Nano Banana tới /v1/images/edits.
  • Với request image-to-image Nano Banana, hãy bỏ qua resolution. nano-banana-2 và nano-banana-pro chỉ công khai resolution cho text-to-image, còn nano-banana không công khai trường này.
  • Ả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 và route upstream tới grok-imagine-image-quality.

​
Thân Yêu Cầu

Timeout cho yêu cầu đồng bộ: một số nhà cung cấp hình ảnh được định tuyến 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
mặc định:"dall-e-3"
Model cần dùng (ví dụ: gpt-image-2, dall-e-3, flux-pro, midjourney).
​
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 họ Nano Banana, đặt operation là image-to-image và bỏ qua resolution trừ khi model hỗ trợ rõ trường này cho operation đó.
​
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_id và images[].
​
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_ratio và resolution hiện không thuộc hợp đồng công khai 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 hợp đồng công khai 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-image-preview, gemini-3-pro-image-preview, nano-banana-2, nano-banana-pro, và các nhóm độ phân giải cao tương tự. 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. Model DALL-E dùng standard hoặc hd; các model GPT Image như gpt-image-2 dùng auto, low, medium hoặc high.
​
response_format
string
mặc định:"url"
Định dạng response: url hoặc b64_json. Mặc định là url.Với các tuyến gpt-image-2 Azure Official hoặc tương thích Azure, TokenLab không chuyển response_format lên upstream. Gateway luôn nhận dữ liệu ảnh upstream dưới dạng b64_json; với request url, gateway 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ẽ fail thay vì fallback về 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
mặc định:"vivid"
Phong cách cho DALL-E 3: vivid hoặc natural.
​
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): Prompt đã được dùng (DALL-E 3)

​
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_id và poll_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-preview",
    "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1
  }'

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

​
Model Khả Dụng

Mô hìnhLoạiTính năng
dall-e-3Thường là inlineChất lượng tốt nhất, cải thiện prompt
dall-e-2Thường là inlineNhanh hơn, chi phí thấp hơn
flux-proThường là taskPhotorealistic, chất lượng cao
flux-schnellThường là inlineRất nhanh
midjourneyThường là taskPhong cách nghệ thuật
ideogram-v3Thường là taskXử lý chữ tốt nhất
stable-diffusion-3Thường là inlineMã nguồn mở, tuỳ biến cao
Đừ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: