🍌 Nano Banana API Documentation

✨ Tạo ảnh AI chất lượng cao với Nano Banana model

📋 Mục lục

1. 🎯 Tổng quan
2. 🔐 Xác thực
3. 💰 Bảng giá Credit
4. 🚀 Endpoints
   • Generate - Tạo ảnh từ text
   • Edit - Chỉnh sửa ảnh
   • Upscale - Tăng độ phân giải
   • Status - Kiểm tra trạng thái
5. ⚠️ Xử lý lỗi

🎯 Tổng quan

Nano Banana API cho phép bạn tạo, chỉnh sửa và tăng độ phân giải ảnh bằng AI với 3 chức năng chính:

• 🎨 Generate: Tạo ảnh mới từ mô tả văn bản
• ✏️ Edit: Chỉnh sửa ảnh hiện có theo hướng dẫn
• 🔍 Upscale: Tăng độ phân giải ảnh (2x hoặc 4x)

Base URL: https://havisoft.vn/api/v1/nano-banana

Phương thức thanh toán: Credit-based (trừ credit ngay khi tạo job)

🔐 Xác thực

Tất cả các request phải bao gồm API Key trong header:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

🔑 Lấy API Key

1. Đăng nhập vào hệ thống Havisoft
2. Vào Profile → API Keys
3. Tạo mới hoặc copy API Key hiện có
4. Sử dụng key này trong header Authorization: Bearer <YOUR_API_KEY>

⚠️ Lưu ý: Bảo mật API Key của bạn. Không chia sẻ hoặc commit vào repository công khai.

💰 Bảng giá Credit

Giá credit được tính dựa trên:

• 💵 Base cost của model Nano Banana
• 📐 Tùy chọn ratio (tỷ lệ khung hình)
• 🖼️ Tùy chọn format (định dạng ảnh)

📊 Xem bảng giá chi tiết: Trang Pricing

Bạn có thể kiểm tra giá credit chính xác cho từng tùy chọn tại trang Pricing của hệ thống. Credit sẽ được trừ ngay khi job được tạo thành công.

🚀 Endpoints

4.1. 🎨 Generate - Tạo ảnh từ text

Tạo ảnh mới từ mô tả văn bản.

Endpoint: POST /api/v1/nano-banana/generate

Request Body

{
  "prompt": "Một cánh rừng tre vàng, phong cách tranh sơn dầu, ánh sáng hoàng hôn",
  "ratio": "16:9",
  "format": "png"
}

Parameters

Response Success

{
  "success": true,
  "TaskId": "task_7e1c41cd4cf6fdce",
  "model": "google/nano-banana",
  "cost": 13,
  "currency": "credits",
  "status": "waiting"
}

Response Fields

4.2. ✏️ Edit - Chỉnh sửa ảnh

Chỉnh sửa ảnh hiện có theo hướng dẫn văn bản.

Endpoint: POST /api/v1/nano-banana/edit

Request Body

{
  "prompt": "Thêm hiệu ứng ánh sáng mặt trời, làm bầu trời xanh hơn",
  "image_urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "ratio": "16:9",
  "format": "png"
}

Parameters

⚠️ Lưu ý: Phải có ít nhất một trong hai: image_urls hoặc image_url

Response Success

{
  "success": true,
  "TaskId": "task_2496a7982a64d676",
  "model": "google/nano-banana-edit",
  "cost": 13,
  "currency": "credits",
  "status": "waiting"
}

4.3. 🔍 Upscale - Tăng độ phân giải

Tăng độ phân giải ảnh lên 2x hoặc 4x.

Endpoint: POST /api/v1/nano-banana/upscale

Request Body

{
  "input_image_url": "https://example.com/image.jpg",
  "input_scale": 4,
  "input_face_enhance": true,
  "input_output_format": "png"
}

Parameters

Response Success

{
  "success": true,
  "TaskId": "task_ae9ce6729e09e633",
  "model": "nano-banana-upscale",
  "cost": 8,
  "currency": "credits",
  "status": "waiting"
}

4.4. 📊 Status - Kiểm tra trạng thái

Kiểm tra trạng thái và kết quả của job.

Endpoint: GET /api/v1/nano-banana/status/{taskId}

Response Success (Job đang xử lý)

{
  "success": true,
  "TaskId": "task_7e1c41cd4cf6fdce",
  "status": "waiting",
  "model": "nano-banana",
  "created_at": "2025-11-12T10:30:00.000000Z",
  "updated_at": "2025-11-12T10:30:15.000000Z"
}

Response Success (Job hoàn thành)

{
  "success": true,
  "TaskId": "task_7e1c41cd4cf6fdce",
  "status": "succeeded",
  "model": "nano-banana",
  "created_at": "2025-11-12T10:30:00.000000Z",
  "updated_at": "2025-11-12T10:35:20.000000Z",
  "result": {
    "image_url": "https://havisoft.vn/storage/images/xxx.png",
    "thumbnail_url": "https://havisoft.vn/storage/images/xxx_thumb.png",
    "format": "png",
    "ratio": "16:9",
    "image_resolution": "1024x1024"
  }
}

Response Success (Job thất bại)

{
  "success": true,
  "TaskId": "task_7e1c41cd4cf6fdce",
  "status": "failed",
  "model": "nano-banana",
  "created_at": "2025-11-12T10:30:00.000000Z",
  "updated_at": "2025-11-12T10:32:10.000000Z",
  "error": {
    "message": "Error message here"
  }
}

Response Error (Không tìm thấy)

{
  "success": false,
  "error": "job_not_found",
  "message": "Không tìm thấy job với TaskId này"
}

⚠️ Xử lý lỗi

🔴 Lỗi xác thực (401)

401 Unauthorized

{
  "error": "missing_api_key"
}

hoặc

{
  "error": "invalid_api_key"
}

💡 Giải pháp: Kiểm tra API Key trong header Authorization: Bearer <KEY>

🟠 Lỗi thiếu credit (402)

402 Payment Required

{
  "success": false,
  "error": "insufficient_credits",
  "required": 13,
  "available": 5
}

💡 Giải pháp: Nạp thêm credit vào tài khoản

🟡 Lỗi validation (422)

422 Unprocessable Entity

{
  "success": false,
  "error": "missing_image_urls"
}

💡 Giải pháp: Kiểm tra request body, đảm bảo các trường bắt buộc đã được gửi đúng format

🔵 Lỗi timeout provider (504)

504 Gateway Timeout

{
  "success": false,
  "error": "provider_timeout",
  "message": "Không nhận được phản hồi hợp lệ từ hệ thống xử lý. Vui lòng thử lại sau.",
  "TaskId": null
}

💡 Giải pháp:

• ✅ Credit đã được hoàn lại tự động
• 🔄 Thử lại request sau vài giây
• 📞 Nếu vẫn lỗi, liên hệ support

⚫ Lỗi không tìm thấy job (404)

404 Not Found

{
  "success": false,
  "error": "job_not_found",
  "message": "Không tìm thấy job với TaskId này"
}

💡 Giải pháp: Kiểm tra lại TaskId hoặc đảm bảo job thuộc về user hiện tại

📈 Trạng thái Job

💡 Best Practices

1. ⏱️ Polling: Nên polling status mỗi 5-10 giây, không quá thường xuyên
2. ⏰ Timeout: Đặt timeout cho request (ví dụ 60 giây)
3. 🔄 Retry: Nếu gặp lỗi provider_timeout, đợi vài giây rồi thử lại
4. ✅ Error Handling: Luôn kiểm tra success field trong response
5. 💰 Credit Management: Kiểm tra credit trước khi gọi API để tránh lỗi insufficient_credits

🆘 Hỗ trợ

Nếu gặp vấn đề hoặc cần hỗ trợ, vui lòng:

• 📋 Kiểm tra log trong hệ thống
• 📧 Liên hệ support qua email hoặc ticket system
• 🔑 Cung cấp TaskId khi báo lỗi để được hỗ trợ nhanh chóng