Comment appeler des modèles d’IA vidéo et image via une seule API asynchrone

Si vous avez déjà intégré la génération de vidéo ou d’images dans un produit, la partie délicate n’est souvent pas le modèle, mais le câblage. Un fournisseur veut un identifiant de tâche à interroger, un autre envoie un callback, un troisième facture à la seconde tandis qu’un quatrième facture à l’image, et chaque corps de requête est un peu différent. Ajouter un nouveau modèle revient généralement à écrire un nouveau client.

NanoAPI s’organise autour d’un contrat plus simple. Vous utilisez une seule clé API, un seul solde prépayé en dollars américains qui n’expire pas, et une seule API de tâches asynchrones pour tous les modèles en ligne. Il n’y a pas d’abonnement. La vidéo est facturée à la seconde, les images à l’image, et les exécutions en échec ne sont pas débitées. L’aire de jeu sur le site utilise les mêmes prix et le même solde que l’API.

Cet article parcourt un véritable appel POST /v1/tasks, la récupération du résultat, et les champs qui figurent réellement dans la documentation officielle — rien de plus.

Créer une clé et recharger une fois

L’URL de base est https://api.nanoapi.ai/v1. L’authentification se fait par jeton bearer :

Authorization: Bearer $NANOAPI_API_KEY

Créez la clé dans Console → API keys. La clé complète n’est affichée qu’une seule fois : stockez-la côté serveur, ne la placez pas dans le code frontal et ne la commitez pas. Rechargez le solde dans la même console. Le solde est prépayé et n’expire pas. À la création d’une tâche, le coût est gelé ; si la tâche échoue, le montant gelé est restitué.

Un seul point d’entrée, on change de modèle avec `model`

Tous les modèles en ligne partagent POST /v1/tasks. Vous choisissez un modèle avec le champ model. Les autres paramètres dépendent de ce modèle et sont documentés sur sa page. Les champs communs du corps de requête sont :

model (chaîne, obligatoire) — par exemple genjutsu-1.0
num_outputs (entier) — obligatoire pour les modèles d’image, de 1 à 4 ; omettez-le pour la vidéo et l’édition (seule la valeur 1 est acceptée)
webhook_url (chaîne, facultatif) — une URL https, jusqu’à 2048 caractères, qui n’est pas une adresse privée, de bouclage ou réservée

L’appel est asynchrone. Il renvoie un identifiant de tâche sans attendre la fin de la génération, généralement en moins d’une seconde. La tâche s’exécute ensuite en arrière-plan et ne peut pas être annulée.

Voici l’exemple officiel de transfert de mouvement Genjutsu 1.0 : une photo d’une personne et une vidéo source, toutes deux sous forme d’URL publiques.

curl https://api.nanoapi.ai/v1/tasks \
  -H "Authorization: Bearer $NANOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c8a2e-3b7d-4c1a-9e6f-2d8b4a1c7e90" \
  -d '{
    "model": "genjutsu-1.0",
    "mode": "motion_control",
    "image_urls": ["https://example.com/person.png"],
    "video_url": "https://example.com/dance.mp4",
    "resolution": "720p",
    "webhook_url": "https://example.com/hooks/nanoapi"
  }'

Une création réussie ressemble à ceci (la valeur created_at est l’exemple de la documentation, pas une date de lancement du produit) :

{
  "code": 200,
  "message": "success",
  "data": {
    "object": "task",
    "id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
    "model": "genjutsu-1.0",
    "status": "queued",
    "error": null,
    "created_at": "2026-10-22T08:30:00Z"
  }
}

Conservez data.id. Vous l’utiliserez pour interroger la tâche ou pour correspondre à un webhook. Un 200 signifie que la tâche a été créée ; ce n’est pas une garantie que la génération réussira. Si un fichier source est illisible, ou si le solde disponible ne couvre pas la tâche, celle-ci peut tout de même être créée puis passer à failed en quelques secondes, sans aucun débit.

Envoyez un en-tête Idempotency-Key (idéalement un UUID, 1 à 255 caractères) à la création. Si la requête expire, renvoyez la même clé et le même corps : une deuxième tâche ne sera pas créée. Une nouvelle tâche exige toujours une nouvelle clé.

Obtenir le résultat : sondage ou webhook

Vous pouvez interroger GET /v1/tasks/{task_id} au plus une fois toutes les 15 secondes jusqu’à ce que status soit succeeded ou failed. Les quatre valeurs possibles sont queued, running, succeeded et failed.

curl https://api.nanoapi.ai/v1/tasks/tk_01jb8z5q4w3e2r1t0y9u8i7o6p \
  -H "Authorization: Bearer $NANOAPI_API_KEY"

En production, ajoutez webhook_url à la création. Le service envoie un seul POST vers cette URL lorsque la tâche se termine — succès ou échec, y compris les tâches qui échouent peu après la création. Rien n’est envoyé au démarrage de la génération. Le corps du webhook est le même objet que celui renvoyé par la consultation de la tâche, donc un seul analyseur suffit. La requête suit Standard Webhooks ; la vérification de signature est facultative. Les fichiers de résultat restent disponibles 15 jours.

Lorsque data.status vaut succeeded, data.outputs[0].url est le fichier à télécharger. Les modèles d’image renvoient un élément par image dans data.outputs. data.billing.charged indique le montant débité. En cas d’échec, lisez data.error.type et n’attendez aucun débit.

Ce que la documentation indique comme disponible

La même clé et le même solde couvrent les modèles vidéo, image et d’édition actuellement en ligne. Côté vidéo : Genjutsu 1.0 (genjutsu-1.0) pour le transfert de mouvement, Genjutsu Lite 1.0 pour le remplacement d’objet à moindre coût, Kling 4.0, Seedance 2.5, Veo 3.1 et Wan 3.0. Côté image : Nano Banana 2.1, GPT Image 2.5, GPT Image 2.6 et Seedream 5.0 Pro. L’édition couvre la suppression d’arrière-plan, l’outpainting, l’agrandissement d’image et de vidéo, et le recadrage vidéo.

Les modèles audio sont annoncés comme à venir, sur la même clé et le même solde ; ils ne sont pas encore en ligne, donc ne construisez pas comme s’ils l’étaient déjà.

Les sorties peuvent être utilisées commercialement, sous réserve des Conditions d’utilisation. NanoAPI n’utilise pas vos contenus pour entraîner des modèles d’IA. Les listes de paramètres, les prix et les types d’erreur se trouvent dans la documentation NanoAPI.

Erreurs à traiter dès la création

Une création en échec renvoie un code 4xx ou 5xx. Un 4xx signifie qu’aucune tâche n’a été créée et que rien n’a été gelé. Branchez-vous sur error.type : invalid_request (400) est un paramètre incorrect ; invalid_api_key (401) signifie que la clé est absente, mal formée, supprimée ou réinitialisée ; insufficient_balance (402) signifie que le solde disponible est à 0, y compris le solde gelé par des tâches en cours ; spend_limit_exceeded (402) signifie qu’une limite de dépense de la clé est épuisée ; account_suspended (403) doit être envoyé à [email protected] ; idempotency_key_reused (409) signifie que la même clé a été réutilisée avec un corps différent ; rate_limited (429) correspond à au plus 20 créations par 10 secondes et par compte, y compris le trafic de l’aire de jeu. Pour un 500, le résultat est inconnu et la tâche a peut-être été créée : renvoyez la requête avec la même clé d’idempotence.

Les problèmes de média, un solde supérieur à zéro mais insuffisant pour cette tâche, et une limite de dépense que cette tâche dépasserait ne sont pas renvoyés comme erreurs de création. Ils sont vérifiés une fois la tâche créée, et la tâche échoue alors avec restitution intégrale du montant gelé.

Une façon pratique d’intégrer

Un schéma proche de cette API consiste à : créer la tâche avec une clé d’idempotence et une URL de webhook, stocker data.id, et traiter le webhook comme source de vérité. N’utilisez le sondage qu’en secours, et pas plus d’une fois toutes les 15 secondes. En cas de délai d’attente ou de 5xx, renvoyez la même clé d’idempotence et le même corps.

Voilà la boucle : une clé, un solde, un POST /v1/tasks, puis un webhook ou un sondage. Ajouter un autre modèle, c’est surtout changer le champ model et les paramètres propres à ce modèle sur sa page de documentation — pas une nouvelle intégration fournisseur.

Auteur : NanoAPI