Nano Banana 2.1 API

Funcționalități

Tarife și credite

Fiecare cerere generează o imagine. Creditele depind de rezoluția de mai jos. Sunt rezervate la acceptare, debitate la succes și restituite în caz de eșec.

Idempotența solicitărilor nu este acceptată. Fiecare cerere POST validă creează un nou task facturabil. Dacă rezultatul trimiterii este incert, verifică taskul folosind taskId returnat; repetarea cererii POST poate crea un alt 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

Raportul de aspect este implicit setat pe auto. Fiecare solicitare generează exact o imagine.

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

Exemplu de răspuns pentru crearea sarcinii

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

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

Imagine în imagine

Pentru editarea imaginilor, setează generation_type la image-to-image și furnizează image_urls. Toți ceilalți parametri respectă aceleași specificații.

Î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-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"
    ]
  }
}'

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-2-1",
  "credits": 3,
  "failed_code": null,
  "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-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
  }
}

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

Linkurile către rezultate sunt disponibile timp de 30 de zile de la stocare. După expirare, câmpul results va fi gol.

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

Callback-urile folosesc structura răspunsului la interogarea unui task; notificările de eșec cu rambursare includ și credits_refunded la nivelul superior. Folosește id pentru a identifica taskul și status pentru a distinge finalizarea cu succes de eșec. Notificările se pot repeta: procesează-le idempotent pe baza id și status. Callback-urile nu sunt semnate; verifică taskul prin endpoint-ul de interogare care necesită autentificare. Eșecul livrării notificării nu duce la rambursarea unui task finalizat cu succes.

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

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

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

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

Erorile folosesc structura error.code și error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. O eroare de tipul 402 insufficient_credits înseamnă că nu aveți suficiente credite disponibile pentru această solicitare.

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.

Solicitările de creare a imaginilor și videoclipurilor folosesc aceeași limită de frecvență a cererilor pentru cheia API.

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