Nano Banana 2 API

ความสามารถ

ราคาและเครดิต

Each image costs 4 credits, including all supported resolutions and formats. Credits are reserved on acceptance, settled on success and refunded on failure. Generation times out after 30 minutes; refund_failed means refund recovery is pending.

Request idempotency is not supported. Each valid POST creates a new billable task. If a submission outcome is uncertain, query the returned taskId; retrying POST can create another task.

การยืนยันตัวตน

สร้างคีย์ API ได้ในแดชบอร์ด โดยระบบจะแสดงคีย์ตัวเต็มเพียงครั้งเดียวเท่านั้น โปรดเก็บรักษาไว้บนเซิร์ฟเวอร์ของคุณและส่งมาในรูปแบบ Bearer token ในทุกรีเควส

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

ตั้งค่าตัวแปรสภาพแวดล้อม SEEVIO_API_KEY ก่อนรันตัวอย่างเหล่านี้ ตัวอย่าง JavaScript จะทำงานบนเซิร์ฟเวอร์ด้วย Node.js ส่วนตัวอย่าง Python จะใช้แพ็กเกจ requests

Request body

พารามิเตอร์อินพุต

Aspect ratio defaults to auto. Unknown fields, including output quantity, are rejected. Each request generates exactly one image.

เริ่มต้นด่วน

ส่งรีเควสแบบย่อนี้ บันทึก taskId ที่ได้รับ จากนั้นใช้ตัวอย่างการสืบค้นสถานะงานด้านล่าง โดยค่าเครดิตที่แสดงในการตอบกลับเมื่อสร้างงานจะเป็นจำนวนเครดิตที่ถูกสำรองไว้

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

ตัวอย่างการตอบกลับเมื่อสร้างงาน

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 4
}

สร้างภาพจากข้อความ

Generate one image asynchronously per request. Supports text-to-image and image-to-image generation with your Seevio API key.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

สร้างภาพจากภาพ

For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract.

โปรดเปลี่ยน URL สื่อของ example.com ให้เป็นไฟล์ HTTPS สาธารณะของคุณเอง URL ตัวอย่างเหล่านี้มีไว้เพื่อแสดงโครงสร้างรีเควสเท่านั้น ไม่ใช่ไฟล์ตัวอย่างที่ดาวน์โหลดได้

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

สืบค้นสถานะงาน

แทนที่ ID ตัวอย่างด้วย taskId ที่ได้จากการสร้างงาน การสืบค้นจะแสดงเฉพาะงานที่เป็นของผู้ใช้คีย์ API นั้นๆ เท่านั้น หากเข้าถึงไม่ได้หรือไม่พบ ID จะส่งคืน HTTP 404

ในเบื้องต้นแนะนำให้สืบค้นสถานะทุกๆ 10–20 วินาที หากพบ HTTP 429 ให้เว้นระยะเวลาเพิ่มขึ้น และหยุดสืบค้นเมื่อสถานะเป็น completed หรือ failed แนะนำให้ใช้เว็บฮุกสำหรับสภาพแวดล้อมจริง ตัวอย่างโค้ดด้านล่างนี้แต่ละชุดจะทำการสืบค้นเพียงหนึ่งครั้ง

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

อยู่ในคิว

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

เสร็จสิ้น

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

ล้มเหลว

เมื่อสถานะที่ส่งกลับมาเป็น status=failed แสดงว่าการสร้างภาพไม่สำเร็จ ให้ดูสาเหตุที่ล้มเหลวได้ใน failed_reason และตรวจสอบผลการคืนเครดิตได้จาก billing_status สำหรับตัวอย่างนี้ refunded หมายถึงระบบได้คืนเครดิตให้แล้ว ส่วน credits จะยังคงแสดงจำนวนเดิมที่เคยสำรองไว้ และจะไม่มีการส่งกลับข้อมูลใน data

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed."
}

Result links are provided for 30 days after storage. After expiry, results is empty.

เว็บฮุก

ตั้งค่า callback_url ในรีเควสการสร้างงานเพื่อรับ JSON POST เมื่อสร้างงานสำเร็จหรือล้มเหลว ระบบปลายทางของคุณต้องส่งการตอบกลับ 2xx กลับมาภายใน 15 วินาที หากส่งไม่สำเร็จระบบจะพยายามส่งซ้ำ โปรดออกแบบระบบรับข้อมูลให้รองรับการทำงานแบบ Idempotent โดยตรวจสอบจาก ID ของงาน

ปลายทางคอลแบ็ก (Callback endpoint) ของคุณต้องรองรับคำขอแบบ POST ที่ส่งข้อมูลมาในรูปแบบ JSON (Content-Type: application/json)

สร้างงานพร้อมกำหนดคอลแบ็ก

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana-2",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Callbacks use the task query response structure; refunded failure notifications also include top-level credits_refunded. Use id to identify the task and status to distinguish completed from failed. Notifications may repeat: process them idempotently by id and status. Callbacks are unsigned; verify the task with the authenticated query endpoint. Delivery failure does not refund a successful task.

งานเสร็จสิ้น: ข้อมูล Callback เมื่อทำรายการสำเร็จ

created_at คือเวลาสร้างเหตุการณ์ ส่วน task_created_at คือเวลาสร้างงาน ทั้งคู่เป็นวินาที Unix ตัวอย่างแสดงฟิลด์ที่แนะนำ โดยข้อมูลตอบกลับอาจมีฟิลด์เพิ่มเติม

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

งานล้มเหลว: ข้อมูล Callback เมื่อทำรายการไม่สำเร็จ

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2",
  "credits": 4,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed.",
  "task_created_at": 1789171200,
  "credits_refunded": 4
}

ตัวอย่างระบบรับข้อมูล

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

ตัวอย่างการใช้งาน Next.js นี้จะอ่านข้อมูล JSON จาก Callback และจัดการกับสถานะงานที่เสร็จสิ้นหรือล้มเหลวโดยตรง ทั้งนี้ ควรเพิ่มระบบจัดเก็บข้อมูล (Persistence) และระบบป้องกันงานซ้ำ (Task-ID deduplication) สำหรับแอปพลิเคชันของคุณ รวมถึงจัดคิวงานที่ใช้เวลาประมวลผลนานก่อนที่จะตอบรับ (Acknowledge) Callback

ข้อผิดพลาด

ข้อผิดพลาด HTTP จะมีออบเจ็กต์ error ซึ่งประกอบด้วย code และ message ทั้งนี้งานที่ระบบรับไปเรียบร้อยแล้วก็ยังอาจล้มเหลวในภายหลังได้ โปรดสืบค้นสถานะงานหรือจัดการผ่านคอลแบ็กความล้มเหลว

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

Errors use error.code and error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Insufficient provider balance is not a customer 402 error.

การจำกัดอัตราการส่งคำขอ

การสร้างงาน: คีย์ API แต่ละคีย์สามารถส่งคำขอได้สูงสุด 100 ครั้งต่อนาทีโดยค่าเริ่มต้น และในขณะนี้ยังไม่รองรับการกำหนดขีดจำกัดอัตราการส่งคำขอแบบกำหนดเอง

การสอบถามข้อมูลงาน: คีย์ API แต่ละคีย์สามารถส่งคำขอได้สูงสุด 120 ครั้งต่อนาทีโดยค่าเริ่มต้น โดยจะนับจำนวนคำขอสอบถามข้อมูลและคำขอสร้างงานแยกกัน

Image and video creation requests share the same API key rate limit.

HTTP 429 จะมี Header Retry-After: 60 สำหรับการสร้างงาน และ Retry-After: 5 สำหรับการสืบค้นสถานะงาน โปรดใช้การเว้นระยะเวลาส่งคำขอ (Backoff) และหลีกเลี่ยงการสืบค้นบ่อยเกินความจำเป็น

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}