Nano Banana 2.1 API

Fonctionnalités

Tarifs et crédits

Chaque requête génère une image. Les crédits dépendent de la résolution indiquée ci-dessous. Ils sont réservés à l’acceptation, débités en cas de succès et remboursés en cas d’échec.

L'idempotence des requêtes n'est pas prise en charge. Chaque requête POST valide crée une nouvelle tâche facturable. Si le résultat d'une soumission est incertain, interrogez le taskId renvoyé ; renvoyer la requête POST risque de créer une autre tâche.

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

Le rapport d'aspect est défini sur auto par défaut. Chaque requête génère exactement une 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-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"
  }
}'

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

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

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

Image vers image

Pour la retouche d'image, définissez generation_type sur image-to-image et renseignez image_urls. Tous les autres paramètres utilisent le même contrat d'interface.

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

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

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

Les liens des résultats restent disponibles pendant 30 jours après leur stockage. Une fois ce délai dépassé, le champ results est vide.

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

Les rappels (callbacks) utilisent la structure de réponse de requête de tâche ; les notifications d'échec remboursées incluent également credits_refunded au niveau supérieur. Utilisez id pour identifier la tâche et status pour distinguer les tâches terminées de celles ayant échoué. Les notifications pouvant être envoyées plusieurs fois, traitez-les de manière idempotente par id et status. Les rappels ne sont pas signés ; vérifiez la tâche à l'aide du point de terminaison de requête authentifié. Un échec de livraison du rappel ne donne pas lieu au remboursement d'une tâche réussie.

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

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

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

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

Les erreurs utilisent error.code et error.message : 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. L'erreur 402 insufficient_credits signifie que votre solde de crédits est insuffisant pour traiter cette requête.

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.

Les requêtes de création d'images et de vidéos partagent la même limite de débit liée à la clé API.

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