Nano Banana API

Funcționalități

Tarife și credite

Each image costs 2 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.

Autentificare

Creează o cheie API în panoul de control. Cheia completă este afișată o singură dată. Păstreaz-o în siguranță pe serverul tău și trimite-o ca token Bearer la fiecare solicitare.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Setează variabila de mediu SEEVIO_API_KEY înainte de a rula aceste exemple. Exemplele în JavaScript rulează pe serverul tău cu Node.js; exemplele în Python utilizează pachetul requests.

Corp solicitare

Parametri de intrare

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

Ghid rapid

Trimite această solicitare minimă, salvează valoarea taskId returnată, apoi folosește exemplul de interogare a sarcinii de mai jos. Valoarea creditelor din răspunsul de creare reprezintă suma rezervată.

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",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Exemplu de răspuns pentru crearea sarcinii

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

Text în imagine

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",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Imagine în imagine

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

Înlocuiește URL-urile media de tip example.com cu propriile tale fișiere accesibile public prin HTTPS. URL-urile din exemplu au scop demonstrativ pentru structura solicitării și nu reprezintă resurse descărcabile.

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",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

Interoghează o sarcină

Înlocuiește ID-ul din exemplu cu valoarea taskId returnată la crearea sarcinii. Interogările returnează doar sarcinile asociate utilizatorului cheii API; ID-urile inaccesibile sau necunoscute returnează HTTP 404.

Ca punct de pornire, interoghează la fiecare 10–20 secunde, redu frecvența în caz de HTTP 429 și oprește interogarea când statusul devine completed sau failed. Pentru mediile de producție, recomandăm utilizarea webhookurilor. Fiecare exemplu de cod de mai jos efectuează o singură interogare.

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

În așteptare

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

Finalizat

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana",
  "credits": 2,
  "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
  }
}

Eșuat

Atunci când interogarea returnează status=failed, procesul de generare s-a încheiat fără succes. Consultați failed_reason pentru a afla cauza și billing_status pentru rezultatul rambursării. În acest exemplu, refunded înseamnă că toate creditele au fost returnate. Parametrul credits păstrează valoarea inițială rezervată, iar răspunsul nu include obiectul data.

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

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

Webhookuri

Setează parametrul callback_url în solicitarea de creare pentru a primi un POST JSON atunci când sarcina se finalizează sau eșuează. Returnează un răspuns de tip 2xx în decurs de 15 secunde. Livrările eșuate vor fi reîncercate; procesează livrările repetate în mod idempotent pe baza ID-ului sarcinii.

Endpoint-ul dumneavoastră de callback trebuie să accepte solicitări de tip POST cu un corp de solicitare JSON (Content-Type: application/json).

Creează o sarcină cu callback

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",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "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.

Sarcină finalizată: payload de callback reușit

created_at este momentul creării evenimentului; task_created_at este momentul creării sarcinii, în secunde Unix. Exemplele arată câmpurile recomandate; răspunsurile pot conține câmpuri suplimentare.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana",
  "credits": 2,
  "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
}

Sarcină eșuată: payload de callback eșuat

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

Exemplu de receptor

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 });
}

Acest exemplu de Next.js citește corpul JSON al callback-ului și gestionează direct sarcinile finalizate și cele eșuate. Adăugați persistență și deduplicare a ID-urilor de sarcini pentru aplicația dumneavoastră; puneți în coadă procesele lente înainte de a confirma callback-ul.

Erori

Erorile HTTP conțin un obiect error cu proprietățile code și message. O sarcină acceptată cu succes poate eșua ulterior; interoghează sarcina sau gestionează callback-ul de eșec primit.

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

Limite de rată

Crearea de sarcini: în mod implicit, fiecare cheie API permite maximum 100 de solicitări pe minut. Limitele personalizate de rată nu sunt disponibile în prezent.

Interogarea sarcinilor: în mod implicit, fiecare cheie API permite maximum 120 de solicitări pe minut. Solicitările de interogare și cele de creare a sarcinilor sunt contorizate separat.

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

Codul HTTP 429 include Retry-After: 60 pentru creare și Retry-After: 5 pentru interogări. Folosește o strategie de backoff și evită interogările mai frecvente decât este necesar.

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

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