Hướng dẫn API Nano Banana: Tạo và chỉnh sửa hình ảnh trên TokenLab

API Nano Banana có ba ID mô hình tính phí trên TokenLab, và mô hình rẻ nhất có chi phí mỗi hình ảnh chỉ bằng khoảng một nửa so với mô hình tầm trung. Sai lầm đắt giá hiếm khi nằm ở việc chọn mô hình. Đó là việc gửi yêu cầu chỉnh sửa đến sai endpoint hoặc thử lại một lệnh tạo (create call) đã tạo ra một tác vụ (task). Hướng dẫn này bao gồm các ID chính xác, một lệnh gọi text-to-image hoạt động, một lệnh gọi reference-image, cơ chế polling bất đồng bộ (async), các lỗi dự kiến và cách tính phí. Giá và danh sách trường được đọc vào ngày 2026-10-03, vì vậy hãy xác nhận lại trước khi bạn triển khai.

Những điểm chính

• Gửi đúng ID: nano-banana-2, nano-banana-2-lite, hoặc nano-banana-pro. Tên hiển thị không phải là bí danh (alias) của yêu cầu.
• Đối với Nano Banana, công việc reference-image được gửi đến POST /v1/images/generations với operation: "image-to-image" và image_urls. Nó không gửi đến /v1/images/edits hay /v1/chat/completions.
• Giá cơ bản chúng tôi đọc được vào ngày 2026-10-03 là $0.0168, $0.0335, và $0.067 mỗi hình ảnh cho các ID lite, tiêu chuẩn và pro. Mỗi mô hình có một dải giá, vì vậy hãy xác nhận cấp độ (tier) chính xác trong phần Usage.
• Phản hồi tạo (create response) với task_id, status: "pending", hoặc poll_url nghĩa là bạn phải poll GET /v1/tasks/{id} cho đến khi trạng thái là completed hoặc failed.
• Việc đọc trạng thái trả về HTTP 200 ngay cả khi tác vụ thất bại. Hãy phân nhánh dựa trên trường status của tác vụ, không phải mã HTTP.
• Phí cuối cùng nằm trong phần Usage và trong billing_transaction_id, không phải trong bảng giá đã sao chép.

Các mô hình API Nano Banana, đơn vị giá và mục đích sử dụng

Khi so sánh bản nháp trước đó của hướng dẫn này với tài liệu hiện tại, chúng tôi đã tìm thấy ba vấn đề. Nó liệt kê các mô hình mà không có giá. Nó gửi một chỉnh sửa Nano Banana thông qua chat completions. Nó truy vấn danh mục với một bộ lọc mà hướng dẫn hình ảnh không sử dụng. Bảng dưới đây khắc phục vấn đề đầu tiên. Các phần sau khắc phục hai vấn đề còn lại.

Model ID	Tốt nhất cho	Đơn vị tính phí	Giá TokenLab (USD)	Nguồn, quan sát
nano-banana-2	Text-to-image và image-to-image với aspect_ratio và resolution (1k, 2k, 4k). Phát hành 2026-02-26.	per_image	$0.0335 mỗi yêu cầu. Dải giá $0.0225 đến $0.0755.	Live model API, 2026-10-03
nano-banana-2-lite	Text-to-image và image-to-image rẻ nhất. Mục giá chúng tôi thấy bao gồm cấp 1k.	per_image	$0.0168 mỗi yêu cầu. Cả tối thiểu và tối đa đều là $0.0168.	Live model API, 2026-10-03
nano-banana-pro	Text-to-image, image-to-image, và chỉnh sửa hình ảnh với aspect_ratio và resolution.	per_image	$0.067 mỗi yêu cầu. Dải giá $0.067 đến $0.12.	Live model API, 2026-10-03
nano-banana	Text-to-image chỉ với aspect_ratio. Không có lựa chọn resolution công khai.	Không có trong bằng chứng của chúng tôi	Kiểm tra trang mô hình hoặc endpoint giá	Catalog, 2026-10-02; Tài liệu Create Image, 2026-10-03

Tất cả các mức giá trên đều có is_lock_price: true và đã được cập nhật vào 2026-10-02T16:53:30.068Z. Ba chi tiết cần lưu ý trước khi bạn chọn:

• Các cấp độ phân giải làm thay đổi giá. API trực tiếp hiển thị một dải giá cho nano-banana-2 và nano-banana-pro, nhưng bằng chứng của chúng tôi không ánh xạ từng cấp độ với một độ phân giải cụ thể. Đừng cho rằng 1k là giá cơ bản. Hãy đọc các mục giá cho mô hình của bạn.
• Đầu ra văn bản có giá token riêng. Cả nano-banana-2 và nano-banana-pro đều có mục native-gemini-text-output. Nó áp dụng khi outputModality là text. Đối với nano-banana-2, nó liệt kê 0.25 đầu vào và 1.5 đầu ra. Đối với nano-banana-pro, nó liệt kê 1 đầu vào và 6 đầu ra. Đơn vị là per_token. Hãy xác nhận thang đo trong GET /v1/models/:model/pricing trước khi lập ngân sách cho nó.
• Lite không liệt kê định dạng yêu cầu được chấp nhận. Bản ghi trực tiếp cho nano-banana-2-lite ghi là "không được liệt kê". Hãy đọc chi tiết của nó trước khi xây dựng dựa trên nó.

Để có ngân sách sơ bộ, chúng tôi nhân giá cơ bản với khối lượng. Đây là các ước tính theo giá cơ bản, không phải báo giá:

• 100 hình ảnh trên nano-banana-2-lite: 100 × $0.0168 = $1.68.
• 100 hình ảnh trên nano-banana-2: 100 × $0.0335 = $3.35.
• 100 hình ảnh trên nano-banana-pro: 100 × $0.067 = $6.70.

Các cấp độ phân giải cao hơn sẽ làm tăng các con số này.

Để tự liệt kê các mô hình hình ảnh hiện tại, hãy gọi endpoint mà hướng dẫn tạo hình ảnh sử dụng. Bản nháp trước đó đã sử dụng category=image, điều mà hướng dẫn không ghi lại.

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Đối với các hoạt động, giá cả và vòng đời của một mô hình, hãy sử dụng Get a Model. Bạn cũng có thể duyệt qua Danh mục mô hình TokenLab.

Gửi yêu cầu text-to-image với API Nano Banana

Tạo một API key trong bảng điều khiển TokenLab và xuất nó:

export TOKENLAB_API_KEY="your-tokenlab-api-key"

Luôn gửi model. Tài liệu Create Image cho biết các API hình ảnh không chọn mặc định. Thiếu mô hình sẽ trả về 400 với param: "model".

Yêu cầu này chỉ sử dụng các trường mà tài liệu liệt kê cho các dòng hình ảnh của Google. Chúng tôi giữ resolution ở mức 1k vì nano-banana-2 ghi lại 1k, 2k, và 4k.

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

Cờ --max-time 120 khớp với tài liệu. Họ nói rằng các yêu cầu độ phân giải 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 client ít nhất là 120 giây. Tài liệu nói rằng size là một bí danh tương thích cho các dòng hình ảnh của Google, nhưng họ khuyên dùng trực tiếp aspect_ratio.

Một phản hồi thành công đồng bộ sẽ trả về hình ảnh đã hoàn thiện. Các giá trị giữ chỗ dưới đây chỉ hiển thị hình dạng được ghi lại:

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

Đọc nó theo thứ tự này:

1. Nếu phần thân có task_id, status: "pending", hoặc poll_url, bạn có một tác vụ, không phải hình ảnh. Hãy chuyển đến phần polling.
2. Nếu không, hãy đọc data[0].url. Với response_format: "b64_json", hãy đọc data[0].b64_json thay thế.
3. created là một dấu thời gian Unix. revised_prompt chỉ xuất hiện khi mô hình trả về một cái, vì vậy đừng yêu cầu nó.
4. Lưu trữ URL hình ảnh, ID công việc của riêng bạn, mô hình và request_id từ các tiêu đề phản hồi.

Các URL hình ảnh được tạo có thể được giữ làm bản sao phương tiện trong 30 ngày. Kiểm tra media_retention.items để biết trạng thái của từng mục và expires_at. Các bản sao đang chờ xử lý hoặc thất bại không được đảm bảo, vì vậy hãy sao chép tệp vào bộ lưu trữ của riêng bạn nếu bạn cần lâu hơn. Hướng dẫn lưu giữ dữ liệu có các chi tiết.

Chỉnh sửa hình ảnh với URL tham chiếu

Hãy tưởng tượng một nhóm danh mục muốn cùng một bức ảnh sản phẩm trên nền studio sạch sẽ. Bước đi hấp dẫn là /v1/images/edits. Tài liệu loại trừ điều đó. Các yêu cầu reference-image của Nano Banana được hiển thị trên /v1/images/generations với operation: "image-to-image". /v1/images/edits không phải là đường dẫn đúng cho chúng.

Yêu cầu này đến từ hướng dẫn tạo hình ảnh, với nano-banana-2 là mô hình:

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Các quy tắc chúng tôi tuân theo với hình dạng này:

• Gửi chính xác các trường tham chiếu được ghi lại. Sử dụng image_url, image_urls, hoặc reference_image_urls trong JSON. Không gửi images[] hoặc file_id cấp cao nhất. Chúng thuộc về luồng chỉnh sửa và bị từ chối trên endpoint này.
• Sử dụng URL công khai. Chúng phải là http hoặc https, không có thông tin xác thực nhúng, không có phân đoạn và không có máy chủ mạng riêng. Tránh các URL đã ký có thể hết hạn trước khi quá trình xử lý bắt đầu.
• Sử dụng multipart cho các nguồn riêng tư. Tài liệu cung cấp tệp image multipart cho các nguồn riêng tư hoặc được bảo vệ bằng tiêu đề.
• Khớp resolution với mô hình. Tài liệu nói rằng nano-banana-pro có thể bao gồm nó và nano-banana-edit nên bỏ qua nó. Tài liệu cũng đặt tên nano-banana-edit là một mô hình reference-image, nhưng ID đó không có trong danh mục chúng tôi đã tìm nạp vào ngày 2026-10-02. Xác minh bất kỳ ID nào so với /v1/models trước khi sử dụng nó.

Ví dụ chỉnh sửa chat-completions của bài viết gốc đã không còn. Bản ghi trực tiếp liệt kê gemini_generate_content là định dạng được chấp nhận cho nano-banana-2 và nano-banana-pro. Bằng chứng của chúng tôi không ghi lại đường dẫn chỉnh sửa hình ảnh chat-completions.

Inpainting dựa trên mặt nạ và các tham số như strength không được ghi lại cho Nano Banana trong bằng chứng của chúng tôi. Kiểm tra GET /v1/models/{model} trước khi bạn gửi chúng.

Khi nào một yêu cầu hình ảnh trở thành tác vụ và cách poll nó

Một lệnh gọi tạo hình ảnh là đồng bộ hoặc bất đồng bộ, và phản hồi cho bạn biết điều đó. Hướng dẫn công việc bất đồng bộ liệt kê các trường kích hoạt: task_id, status: "pending", hoặc poll_url. Nếu bất kỳ trường nào xuất hiện, mảng data[] trống và công việc vẫn đang chạy.

Bằng chứng của chúng tôi chỉ ghi lại cờ yêu cầu async: true cho gpt-image-2 và các mô hình hình ảnh FLUX/BFL chính thức. Nó không ghi lại cho các ID Nano Banana. Đừng thêm nó vào yêu cầu Nano Banana. Xử lý phản hồi tác vụ nếu nó trả về và kiểm tra chi tiết mô hình nếu bạn cần hành vi bất đồng bộ.

Hãy tưởng tượng việc làm mới trình duyệt gửi lại lệnh gọi tạo sau một phản hồi chậm. Bây giờ bạn phải trả tiền cho hai lần tạo. Tài liệu nói rằng hầu hết các lần tạo trùng lặp đến từ việc thử lại này. Hãy tuân theo thứ tự này:

1. Lưu ID ngay lập tức. Lưu id hoặc task_id, poll_url, mô hình, endpoint và ID công việc của riêng bạn. id và task_id là cùng một giá trị.
2. Poll URL. Sử dụng poll_url khi có mặt. Nếu không, hãy gọi tuyến đường cố định:

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

1. Poll mỗi 5–10 giây. Hướng dẫn nói rằng điều đó thường đủ cho các công việc phương tiện dài.
2. Biết các trạng thái. Chúng là pending, processing, completed, và failed. Một tác vụ bị hủy hiển thị failed với cancelled: true.
3. Dừng ở trạng thái cuối cùng. Khi completed, đọc data[].url. Kết quả hình ảnh bất đồng bộ chỉ là URL, không bao giờ là b64_json. Khi failed, đọc error và error_details.
4. Xử lý thời gian chờ một cách an toàn. Nếu một lệnh gọi tạo hết thời gian chờ trước khi bạn thấy phản hồi, hãy kiểm tra request_id và tìm tác vụ trước khi thử lại. Nếu bạn đã lưu ID tác vụ, hãy tiếp tục poll nó. Nếu một lần poll trạng thái thất bại, hãy thử lại lần poll đó với backoff và không tạo lại.

Việc đọc trạng thái trả về HTTP 200 ngay cả đối với tác vụ thất bại. Các tác vụ thất bại có thể bao gồm error_details với status, type, code, message, param, và retryable. Ví dụ, error_details.status: 400 với param: "size" nghĩa là yêu cầu cần sửa chữa. Nó không có nghĩa là bản thân lần poll thất bại. Việc thử lại một lần tạo thất bại sẽ tạo ra một tác vụ mới và có thể tạo ra một khoản phí mới.

Các lỗi cần dự kiến và cách xử lý

Xử lý lỗi theo trạng thái HTTP và code, không bao giờ theo message. Hướng dẫn xử lý lỗi nói rằng thông báo có thể thay đổi mà không cần báo trước. Chat Completions và Responses sử dụng đối tượng error kiểu OpenAI, trong khi các định dạng Gemini và Anthropic giữ hình dạng riêng của chúng. Đừng chia sẻ một trình phân tích cú pháp (parser) trên tất cả các API TokenLab.

Trạng thái / code	Nguyên nhân có thể	Cách thực hiện
400, param: "model"	Không có mô hình rõ ràng	Gửi model. Liệt kê các ID với /v1/models?recommended_for=image.
400 trường không được hỗ trợ, hoặc unsupported_parameter	Một trường mà mô hình không ghi lại, chẳng hạn như resolution trên một mô hình không có nó	Xóa trường hoặc chuyển mô hình. Đừng lặp lại nếu không thay đổi.
400 trên một hình ảnh tham chiếu	Sai endpoint, hoặc URL riêng tư hoặc đã hết hạn	Sử dụng /v1/images/generations với image_urls. Sử dụng URL công khai, ổn định.
401 invalid_api_key hoặc expired_api_key	Thiếu, bị thu hồi hoặc hết hạn key	Thay thế key.
402 insufficient_balance hoặc quota_exceeded	Số dư quá thấp, hoặc key đạt giới hạn của chính nó	Thêm tiền, tăng giới hạn key, hoặc chọn mô hình giá thấp hơn.
403 model_not_allowed	Key không thể sử dụng mô hình đó	Cập nhật danh sách mô hình của key.
404 model_not_found	ID không xác định hoặc không khả dụng	Đọc /v1/models và sử dụng ID hiện tại.
413 payload_too_large	Yêu cầu hoặc tệp quá lớn	Giảm đầu vào.
429 rate_limit_exceeded	Quá nhiều yêu cầu trong cửa sổ thời gian	Chờ Retry-After, sau đó thử lại.
500–504, all_channels_failed	Vấn đề dịch vụ hoặc nguồn cung	Chỉ thử lại khi retryable là true. Tôn trọng retry_after và giới hạn số lần thử.

Một lỗi 503 all_channels_failed không phải lúc nào cũng có nghĩa là ngừng hoạt động. Nếu retryable là false và retry_after bị thiếu, hoạt động không có nguồn cung trong cấp độ Giao hàng đã chọn. Việc lặp lại yêu cầu sẽ không giúp ích gì, vì vậy hãy kiểm tra GET /v1/models trước.

Việc poll tác vụ có những thất bại riêng:

• 404 async_task_not_found: tác vụ đã hết hạn hoặc không còn. Kiểm tra task_id và poll_url đã lưu.
• 403 task_not_owned: tác vụ thuộc về một không gian làm việc khác. Kiểm tra xem API key thuộc về không gian làm việc nào.
• Một tác vụ đã hoàn thành không có URL phương tiện: hãy coi nó là thất bại. Giữ các ID và liên hệ với bộ phận hỗ trợ.

Khi bạn liên hệ với bộ phận hỗ trợ, hãy gửi request_id, task_id, billing_transaction_id khi có mặt, endpoint, mô hình, thời gian và tên trường. Không bao giờ gửi key, phương tiện riêng tư hoặc URL đã ký.

Cách xác định phí cho một yêu cầu hình ảnh

Cả ba ID Nano Banana có tính phí đều sử dụng đơn vị per_image, vì vậy phí tiêu đề là giá per_request của mô hình. Hướng dẫn thanh toán thêm các quy tắc xung quanh nó:

• Một kết quả, một khoản phí. Mỗi yêu cầu hoàn thành được tính phí một lần, cho tùy chọn giao hàng đã tạo ra nó. TokenLab Verified sử dụng giá công khai của TokenLab. Official sử dụng lớp giá Chính thức. Auto thử Verified trước, sau đó đến Official.
• Các cấp độ thiết lập con số cuối cùng. Các dải giá trực tiếp ($0.0225 đến $0.0755 cho nano-banana-2, $0.067 đến $0.12 cho nano-banana-pro) cho thấy một mức giá cố định không bao gồm mọi yêu cầu. Các cấp độ phân giải có khả năng là yếu tố thúc đẩy, nhưng hãy xác nhận điều đó trong các mục giá của mô hình.
• Tác vụ dự trữ trước. Một tác vụ bất đồng bộ có thể dự trữ chi phí ước tính của nó khi được chấp nhận. Một tác vụ hoàn thành được tính phí một lần, và một tác vụ thất bại sẽ giải phóng hoặc hoàn lại số tiền đang chờ xử lý. Hướng dẫn thanh toán nói rằng một tác vụ thất bại không bị tính phí.
• Một dấu gạch ngang không có nghĩa là miễn phí. Trên trang Models, một dấu gạch ngang trong cột giá TokenLab có nghĩa là không có ưu đãi Verified nào khả dụng ngay bây giờ.

Để xác nhận một khoản phí, hãy sử dụng các nơi này:

1. GET /v1/models/:model/pricing hoặc Pricing API cho giá hiện tại.
2. Bảng điều khiển, hiển thị ước tính tối đa trước khi bạn xác nhận tạo có trả phí.
3. Usage cho khoản phí cuối cùng theo mô hình.
4. billing_transaction_id trong phản hồi hoặc tác vụ, và tiêu đề X-Billing-Transaction-ID. Streaming và một số định dạng gốc có thể chỉ hiển thị nó trong tiêu đề.

Nếu Usage không hiển thị khoản phí cuối cùng hoặc số tiền đã giải phóng sau khi tác vụ kết thúc, hãy gửi Request ID và task ID đến support@tokenlab.sh. Đừng sao chép giá trong bài viết này vào mã của bạn. Hướng dẫn thanh toán nói rằng hãy đọc giá hiện tại khi ứng dụng của bạn cần hiển thị hoặc so sánh chi phí.

Câu hỏi thường gặp

Tôi nên gửi ID mô hình Nano Banana nào cho các yêu cầu image-to-image?

Các bản ghi trực tiếp liệt kê image-to-image cho nano-banana-2, nano-banana-2-lite, và nano-banana-pro. Tài liệu cũng đặt tên nano-banana-edit, nhưng nó không có trong danh mục chúng tôi đã tìm nạp vào ngày 2026-10-02. Gửi ID với operation: "image-to-image" và image_urls đến /v1/images/generations. Chạy một thử nghiệm nhỏ trên hình ảnh của riêng bạn, vì bằng chứng của chúng tôi không có so sánh chất lượng.

Tại sao yêu cầu hình ảnh của tôi trả về task_id thay vì một hình ảnh?

Lệnh gọi tạo đã chạy như một tác vụ bất đồng bộ. Tìm task_id, status: "pending", hoặc poll_url trong phản hồi. Lưu các trường đó, sau đó poll poll_url hoặc GET /v1/tasks/{id} mỗi 5–10 giây cho đến khi trạng thái là completed hoặc failed. Đừng gửi yêu cầu tạo thứ hai trong khi bạn chờ đợi.

Tôi có thể nhận đầu ra base64 từ mô hình Nano Banana không?

Trường response_format chấp nhận url hoặc b64_json, và một yêu cầu đồng bộ có thể trả về data[].b64_json. Kết quả hình ảnh bất đồng bộ chỉ là URL, bất kể định dạng bạn đã yêu cầu. Kiểm tra chi tiết của mô hình đã chọn để xác nhận nó chấp nhận b64_json, vì các trường khác nhau tùy theo mô hình.

Một tác vụ hình ảnh thất bại có bị tính phí không?

Hướng dẫn thanh toán nói rằng một tác vụ thất bại không bị tính phí, và bất kỳ khoản dự trữ nào đang chờ xử lý sẽ được giải phóng hoặc hoàn lại. Việc thử lại một lần tạo thất bại sẽ tạo ra một tác vụ mới và có thể tạo ra một khoản phí mới. Xác nhận kết quả trong Usage bằng cách sử dụng billing_transaction_id và task_id.

Tạo một key trong bảng điều khiển TokenLab, gửi yêu cầu text-to-image ở trên với nano-banana-2-lite, và kiểm tra khoản phí trong Usage.