Passer à la documentation
Sur cette page

Nano Banana 2.1 API

Generate one image asynchronously per request. Supports text-to-image and image-to-image generation with your Seevio API key.

POST https://api.seevio.ai/v1/images/generations

Fonctionnalités

FonctionnalitéValeurs acceptées
Modes de générationtext-to-image, image-to-image
Résolution de sortie1K, 2K, 4K
Format d'imageauto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9, 4:1, 1:4, 8:1, 1:8
Images de référencePublic HTTPS PNG / JPEG / WebP URLs. Image-to-image requires 1–10 images, each up to 30 MB. Text-to-image requires an empty array.
PromptRequired non-empty prompt, up to 20000 characters.
Format de sortiepng, jpg

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.

Résolution de sortieTarifs et crédits
1K2 crédits
2K3 crédits
4K4 crédits

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.

URL de base

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

ChampTypeRequisDescription et contraintes
model
stringOui

Identifiant du modèle. Pour utiliser Nano Banana 2.1, définissez ce champ sur nano-banana-2-1.

callback_url
stringNon

Point de terminaison HTTPS public pour recevoir les appels POST en cas de succès ou d'échec. Les réseaux privés et localhost ne sont pas autorisés.

Exemple: https://example.com/webhooks/seevio
input
objectOui

Paramètres de génération. Doit contenir un prompt non vide.

Paramètres d'entrée

ChampTypeRequisPar défautDescription et contraintes
input.prompt
stringOui—

Required non-empty prompt, up to 20000 characters.

Exemple: A minimalist ceramic teapot on a stone pedestal, soft studio lighting
input.generation_type
stringNontext-to-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.

Valeurs acceptées
text-to-image | image-to-image
input.image_urls
string[]Sous conditions[]

Public HTTPS PNG / JPEG / WebP URLs. Image-to-image requires 1–10 images, each up to 30 MB. Text-to-image requires an empty array.

Exemple: ["https://example.com/teapot.png"]
input.aspect_ratio
stringNonauto

Format d'image

Valeurs acceptées
auto | 1:1 | 16:9 | 9:16 | 4:3 | 3:4 | 3:2 | 2:3 | 5:4 | 4:5 | 21:9 | 4:1 | 1:4 | 8:1 | 1:8
Exemple: 1:1
input.resolution
stringNon2K

Utilisez l'une des résolutions de sortie prises en charge et répertoriées ici.

Valeurs acceptées
1K | 2K | 4K
Exemple: 2K
input.output_format
stringNonpng
Valeurs acceptées
png | jpg
Exemple: png

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

GET https://api.seevio.ai/v1/tasks/{taskId}

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"
StatutValeurs autorisées et critères requis
queuedAcceptée et en attente de traitement.
generatingGénération en cours.
completedSuccès. Téléchargez le contenu de data.results avant son expiration.
failedÉchec définitif. Examinez failed_reason et billing_status.
ChampTypeValeurs autorisées et critères requis
idstringIdentifiant de la tâche. Il s'agit du taskId obtenu lors de la création.
created_atnumberDate de création de la tâche au format horodatage Unix (en secondes).
modelstringID public du modèle utilisé pour cette tâche.
billing_statusstringStatut de facturation : reserved, charged, refunded ou refund_failed.
creditsnumberCrédits réservés pour cette tâche. Cette valeur est conservée même après un remboursement ; fiez-vous au billing_status pour connaître l'issue de la facturation.
failed_reasonstring | nullRaison de l'échec pour les tâches ayant échoué ; null dans les autres cas. Les réponses d'interrogation en échec n'incluent pas l'objet data.
failed_codestring | nullCode d’erreur. Consultez failed_reason pour plus de détails.
dataobjectPrésent pour les requêtes de tâches qui n'ont pas échoué. Contient les fichiers de sortie et les détails du traitement.
data.resultsstring[]Tableau des URL des images, vide avant la fin et après expiration.
data.image_expires_atstring | nullExpiration des images au format ISO 8601, ou null si indisponible.
data.processing_timenumber | nullDurée de traitement de la tâche en secondes si elle est disponible, sinon null.

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.