Tạo hình ảnh

Tổng quanCopy Anchor Link

Sử dụng GET /v1/models?recommended_for=image để lấy các model hình ảnh hiện tại, sau đó gửi model đã chọn một cách tường minh.

gpt-image-2 là một model GPT Image tính phí theo token. TokenLab tuân theo bảng phân bổ sử dụng chính thức của OpenAI cho đầu vào văn bản, đầu vào hình ảnh, đầu vào được lưu trong bộ nhớ đệm (cached input) và token đầu ra hình ảnh; model này không được tính phí cố định theo mỗi hình ảnh.

Đối với việc tạo hình ảnh bằng gpt-image-2, các tham số công khai được hỗ trợ bao gồm prompt, n, size, quality, response_format, async, background, output_format, output_compression hoặc compression, moderation và user. background chấp nhận giá trị auto hoặc opaque; transparent không được hỗ trợ. Hãy bỏ qua size hoặc quality để TokenLab sử dụng giá trị auto; các giá trị size tùy chỉnh phải tuân theo hợp đồng WIDTHxHEIGHT linh hoạt được ghi lại bên dưới.

input_fidelity không nằm trong các trường được TokenLab hỗ trợ hiện tại cho gpt-image-2; hãy bỏ qua tham số này nếu không yêu cầu sẽ trả về lỗi 400 unsupported_parameter.

Lưu ý về hành vi của ModelCopy Anchor Link

Các model thuộc dòng hình ảnh Google Gemini không chia sẻ cùng một hợp đồng chọn model:

• gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, nano-banana-2.1 và nano-banana-pro hỗ trợ aspect_ratio cộng với resolution (1k, 2k, 4k) cho các thao tác text-to-image, image-to-image và image-edit công khai.
• nano-banana-2 hỗ trợ aspect_ratio và resolution (1k, 2k, 4k) cho cả tạo hình ảnh từ văn bản (text-to-image) và từ hình ảnh (image-to-image).
• gemini-3.1-flash-lite-image và nano-banana-2-lite hỗ trợ text-to-image, image-to-image và image-edit chỉ ở độ phân giải 1k.
• nano-banana hỗ trợ aspect_ratio nhưng không hiển thị lựa chọn resolution công khai.
• Đối với image-to-image với gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image hoặc gemini-3-pro-image, hãy sử dụng endpoint này với operation: "image-to-image" và các hình ảnh tham chiếu. Gửi các yêu cầu image-edit cho các model này đến /v1/images/edits.
• Đối với các yêu cầu hình ảnh tham chiếu Nano Banana, hãy sử dụng nano-banana-2, nano-banana-2.1, nano-banana-2-lite hoặc nano-banana-pro trên endpoint này (/v1/images/generations) với operation: "image-to-image" và image_urls. Các yêu cầu image-edit cho nano-banana-2, nano-banana-2.1, nano-banana-2-lite và nano-banana-pro cũng sử dụng endpoint này, với operation: "image-edit". Không gửi các yêu cầu hình ảnh tham chiếu Nano Banana đến /v1/images/edits.
• Hình ảnh tham chiếu trên endpoint này có thể được cung cấp dưới dạng JSON image_url / image_urls, hoặc dưới dạng tệp multipart image. images[] và file_id không được chấp nhận trên /v1/images/generations; chỉ tạo các tham chiếu /v1/files cho các model /v1/images/edits có tài liệu ghi nhận images[].file_id.

Đối với các dòng hình ảnh Google, hãy ưu tiên sử dụng 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-2.0 và model cũ grok-imagine-image-pro) hỗ trợ aspect_ratio cộng với resolution (1k, 2k). grok-imagine-image-pro được giữ lại như một ID tương thích cho grok-imagine-image-2.0.

Phần thân yêu cầuCopy Anchor Link

Thời gian chờ yêu cầu đồng bộ (Synchronous request timeout): Một số yêu cầu hình ảnh trả về hình ảnh cuối cùng ngay lập tức và chờ quá trình tạo hoàn tất. Các yêu cầu có độ 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 thời gian chờ (timeout) của HTTP client của bạn ít nhất là 120s. Nếu phản hồi tạo hình ảnh bao gồm status: "pending", task_id hoặc poll_url, hãy làm theo poll_url được trả về.

Phản hồiCopy Anchor Link

Phản hồi nội tuyến (Inline Response)Copy Anchor Link

Phản hồi tác vụ Async (Async Task Response)Copy Anchor Link

Đặt async: true với gpt-image-2 hoặc các model hình ảnh FLUX/BFL chính thức để tạo một tác vụ thay vì chờ đợi hình ảnh cuối cùng trong yêu cầu tạo. Phản hồi bao gồm status: "pending", task_id và poll_url. Hãy thăm dò (poll) /v1/tasks/{task_id} cho đến khi tác vụ đạt trạng thái completed hoặc failed.

Các tác vụ hình ảnh async chỉ trả về URL hình ảnh cuối cùng. Nếu bạn cần dữ liệu hình ảnh b64_json thô, hãy sử dụng yêu cầu đồng bộ.

Việc thanh toán có thể giữ trước số tiền ước tính khi tác vụ được tạo. Các tác vụ đã hoàn thành được tính phí theo mức sử dụng thực tế, và các tác vụ thất bại hoặc hết thời gian chờ sẽ được hoàn lại hoặc hủy bỏ.

Khi bạn nhận được status: "pending", hãy sử 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"
  }'

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

Chọn một ModelCopy Anchor Link

Truy vấn GET /v1/models?recommended_for=image hoặc sử dụng trang Models để biết tính khả dụng, khả năng và giá cả hiện tại.

Không nên mã hóa cứng (hard-code) một model là luôn đồng bộ hoặc luôn bất đồng bộ. Nếu phản hồi tạo hình ảnh trả về status: "pending", hãy làm theo poll_url và thăm dò cho đến khi hoàn tất.

Xử lý các phản hồi dựa trên tác vụCopy Anchor Link

Đối với các model hình ảnh, luôn kiểm tra xem phản hồi có chứa status: "pending" / status: "processing" hay không:

import requests
import time

def generate_image(prompt, model="gpt-image-2"):
    # Tạo yêu cầu hình ảnh
    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()

    # Kiểm tra xem có dựa trên tác vụ không
    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}")

        # Thăm dò kết quả
        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:
        # Phản hồi nội tuyến
        return data["data"][0]["url"]

# Sử dụng
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"
}