Nano Banana 2.1 API

ความสามารถ

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

แต่ละคำขอสร้างภาพหนึ่งภาพ จำนวนเครดิตขึ้นอยู่กับความละเอียดในตารางด้านล่าง ระบบสำรองเครดิตเมื่อรับงาน หักเมื่อสำเร็จ และคืนเมื่อไม่สำเร็จ

ระบบไม่รองรับคุณสมบัติ Idempotency ของคำขอ การส่งคำขอ POST ที่ถูกต้องแต่ละครั้งจะสร้างงานใหม่ที่มีค่าใช้จ่าย หากไม่แน่ใจผลลัพธ์ของการส่งข้อมูล ให้ตรวจสอบจาก taskId ที่ได้รับคืนมา การส่งคำขอ POST ซ้ำอาจทำให้เกิดการสร้างงานใหม่ซ้ำซ้อน

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

สร้างคีย์ 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

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

อัตราส่วนภาพเริ่มต้นจะเป็นแบบ auto โดยการขอใช้งานแต่ละครั้งจะสร้างรูปภาพขึ้นมาเพียงรูปเดียวเท่านั้น

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

ส่งรีเควสแบบย่อนี้ บันทึก 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-1",
  "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": 3
}

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

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-1",
  "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"
  }
}'

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

สำหรับการแก้ไขรูปภาพ ให้ตั้งค่า generation_type เป็น image-to-image และระบุ image_urls ส่วนพารามิเตอร์อื่นๆ ทั้งหมดให้ใช้ข้อกำหนดเดียวกัน

โปรดเปลี่ยน 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-1",
  "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-1",
  "credits": 3,
  "failed_code": null,
  "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-1",
  "credits": 3,
  "failed_code": null,
  "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-1",
  "credits": 3,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

ลิงก์ผลลัพธ์จะสามารถใช้งานได้เป็นเวลา 30 วันหลังจากบันทึกข้อมูล เมื่อหมดอายุแล้ว ผลลัพธ์ในช่อง results จะว่างเปล่า

เว็บฮุก

ตั้งค่า 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-1",
  "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) จะใช้โครงสร้างการตอบกลับเหมือนกับการสอบถามข้อมูลงาน (task query) สำหรับการแจ้งเตือนกรณีที่ดำเนินการไม่สำเร็จและมีการคืนเครดิต จะมีฟิลด์ credits_refunded แสดงอยู่ในระดับบนสุดด้วย ให้ใช้ id ในการระบุงาน และใช้ status เพื่อแยกแยะระหว่างงานที่เสร็จสมบูรณ์กับงานที่ล้มเหลว ทั้งนี้ การแจ้งเตือนอาจเกิดขึ้นซ้ำได้ จึงควรประมวลผลแบบ Idempotent โดยอ้างอิงจาก id และ status การเรียกกลับจะไม่มีการลงลายมือชื่อดิจิทัล (Unsigned) ดังนั้นโปรดตรวจสอบความถูกต้องของงานผ่าน Endpoint สอบถามงานที่ต้องยืนยันตัวตน ทั้งนี้ หากการส่งข้อมูลเรียกกลับล้มเหลว จะไม่มีการคืนเครดิตสำหรับงานที่ดำเนินการสำเร็จแล้ว

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

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

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana-2-1",
  "credits": 3,
  "failed_code": null,
  "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-1",
  "credits": 3,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 3
}

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

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

ข้อผิดพลาดจะใช้รูปแบบ error.code และ error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error โดยข้อผิดพลาด 402 insufficient_credits หมายถึงยอดเครดิตคงเหลือของคุณไม่เพียงพอสำหรับการส่งคำขอนี้

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

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

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

คำขอสร้างรูปภาพและวิดีโอจะใช้ขีดจำกัดอัตราการส่งคำขอ (Rate limit) ร่วมกันภายใต้ API key เดียวกัน

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