Nano Banana API

Fonctionnalités

Tarifs et crédits

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.

Authentification

Générez une clé API depuis votre tableau de bord. La clé complète ne s'affiche qu'une seule fois. Conservez-la en toute sécurité sur votre serveur et transmettez-la comme jeton Bearer lors de chaque requête.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Définissez la variable d'environnement SEEVIO_API_KEY avant d'exécuter ces exemples. Les exemples en JavaScript s'exécutent sur votre serveur avec Node.js ; les exemples en Python utilisent la bibliothèque requests.

Corps de la requête

Paramètres d'entrée

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

Démarrage rapide

Envoyez cette requête minimale, enregistrez le taskId renvoyé, puis utilisez l'exemple d'interrogation de tâche ci-dessous. Le montant des crédits affiché dans la réponse de création correspond à la provision réservée.

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

Exemple de réponse à la création de tâche

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

Texte vers image

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

Image vers image

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

Remplacez les URL d'exemple d'example.com par vos propres fichiers accessibles via HTTPS public. Les URL d'illustration servent uniquement à montrer la structure de la requête et ne pointent pas vers des ressources téléchargeables.

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

Interroger une tâche

Remplacez l'ID d'exemple par le taskId obtenu lors de la création. Les requêtes renvoient uniquement les tâches créées par l'utilisateur de la clé API ; les identifiants inconnus ou inaccessibles renvoient une erreur HTTP 404.

Nous vous suggérons d'interroger l'API toutes les 10 à 20 secondes au début, d'espacer les requêtes en cas d'erreur HTTP 429 et d'arrêter dès que le statut est completed ou failed. Privilégiez les webhooks pour la production. Chaque exemple de code ci-dessous effectue une seule interrogation.

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

En file d’attente

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

Terminée

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

Échouée

Lorsque la requête renvoie status=failed, la génération a échoué. Consultez le champ failed_reason pour en connaître la cause et billing_status pour le statut du remboursement. Dans cet exemple, refunded signifie que les crédits ont été restitués. Le champ credits conserve le montant initialement réservé, et la réponse ne contient pas de nœud 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.

Webhooks

Configurez le champ callback_url dans votre requête de création pour recevoir un POST JSON lorsque la tâche se termine ou échoue. Renvoyez une réponse HTTP 2xx sous 15 secondes. En cas d'échec de distribution, de nouvelles tentatives seront effectuées ; gérez les doublons de manière idempotente grâce à l'identifiant de la tâche.

Votre point de terminaison de rappel (callback) doit accepter les requêtes POST contenant un corps de requête JSON (Content-Type : application/json).

Créer une tâche avec un webhook de 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.

Tâche terminée : charge utile du callback réussi

created_at indique la création de l’événement ; task_created_at indique celle de la tâche, en secondes Unix. Les exemples présentent les champs recommandés ; les réponses peuvent contenir des champs supplémentaires.

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

Échec de la tâche : charge utile du callback d'échec

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

Exemple de réception de webhook

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

Cet exemple Next.js lit le corps JSON du callback et traite directement les tâches réussies et échouées. Pour votre application de production, pensez à ajouter une couche de persistance, à dédoublonner les identifiants de tâche (task-ID) et à placer les tâches lourdes en file d'attente avant d'accuser réception du callback.

Erreurs

Les erreurs HTTP contiennent un objet error avec un code (code) et un message (message). Une tâche acceptée avec succès peut toujours échouer ultérieurement ; interrogez régulièrement la tâche ou configurez un webhook pour suivre son statut.

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

Limites de requêtes

Création de tâches : chaque clé API permet par défaut jusqu'à 100 requêtes par minute. Il n'est actuellement pas possible de personnaliser ces limites de débit.

Consultation de tâches : chaque clé API permet par défaut jusqu'à 120 requêtes par minute. Les requêtes de consultation et de création de tâches sont comptabilisées séparément.

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

L'erreur HTTP 429 renvoie l'en-tête Retry-After: 60 pour la création et Retry-After: 5 pour les requêtes d'interrogation. Utilisez une stratégie d'attente progressive (backoff) et évitez d'interroger l'API plus souvent que nécessaire.

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

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