L'API Fellowi fait maintenant de la vidéo : clés, modèles, 1re requête

Jusqu'à récemment, l'API Fellowi faisait une seule chose : du texte en entrée, une image en sortie. Elle en fait désormais bien davantage. La même clé génère des clips vidéo, vous choisissez le modèle pour les images comme pour la vidéo, et l'API Console les liste tous avec leur prix, pour que personne n'ait à deviner. Si votre produit a besoin d'images ou de courts mouvements et que vous ne voulez pas faire tourner une ferme de GPU pour ça, cet article est pour vous.

Ce qui a changé, en bref

• La vidéo avec la même clé. Image-to-video, text-to-video et clips guidés par des références, avec le même solde et la même forme de requête que les images.
• Un champ model. Un modèle plus rapide et moins cher pour les brouillons, un plus puissant pour le rendu final. Pour les images, vous pouvez l'omettre et obtenir exactement ce qu'une ancienne intégration a toujours obtenu, au même prix ; une requête vidéo nomme toujours son modèle.
• Un catalogue lisible par votre code. GET /v1/api/models renvoie ce que votre clé peut appeler et ce que chaque modèle coûte : votre application peut construire son propre sélecteur au lieu d'embarquer une liste qui vieillit.
• Un raccourci pour l'intégration elle-même. La console a un bouton « Copy for ChatGPT/Claude » qui copie toute la référence d'un coup. Collez-la dans votre assistant de code et demandez un client dans votre langage.

Obtenir une clé

Créez un compte gratuit, ouvrez /api-console, nommez une clé et créez-la. La clé complète n'est affichée qu'une seule fois ; ensuite la console ne garde qu'un aperçu, alors copiez-la tout de suite dans votre coffre à secrets. Chaque requête la transmet en en-tête bearer :

Authorization: Bearer fk_live_your_key_here

Utilisez une clé par environnement ou par produit. Chaque clé peut avoir son propre plafond quotidien de coins : le moyen le plus simple d'éviter qu'un bug dans une boucle de test ne vide votre solde pendant la nuit.

Votre première image

Une génération est asynchrone. Vous la mettez en file, vous recevez aussitôt 202, et l'image arrive un peu plus tard :

POST /v1/api/images
Content-Type: application/json
Authorization: Bearer fk_live_your_key_here
Idempotency-Key: 7f1c2b90-order-4411

{
  "prompt": "a ceramic mug on a linen cloth, soft window light",
  "quality": "standard",
  "aspectRatio": "4:5"
}

L'en-tête Idempotency-Key compte plus qu'il n'y paraît. Les réseaux perdent des réponses ; avec lui, une nouvelle tentative de la même requête renvoie la même génération au lieu de payer deux fois. Créez-en un par tentative, par exemple à partir de votre propre identifiant de commande. Puis interrogez jusqu'à ce que ce soit prêt et téléchargez le résultat :

GET /v1/api/images/{id}          -> "queued" ... "succeeded"
GET /v1/api/images/{id}/content  -> the image bytes

quality, format, aspectRatio et un optimiseur de prompt payant sont tous facultatifs, et chaque valeur par défaut correspond à ce que faisait l'API avant l'arrivée de l'option. Ajoutez quelques URL d'images de référence dans images et la requête passe sur le modèle d'édition : c'est ainsi qu'un personnage ou un produit reste reconnaissable d'une image à l'autre.

Choisir un modèle

GET /v1/api/models

Cet appel renvoie les modèles image et vidéo accessibles à votre clé, avec leurs prix en coins et, pour la vidéo, la durée maximale de clip, les résolutions proposées et le besoin ou non d'une image de départ. Passez celui que vous voulez dans model. Un bon schéma : un modèle bon marché pendant que l'utilisateur explore, le plus puissant pour la version qu'il garde. Les chiffres actuels figurent aussi sur la page produit, qui les lit dans le code même qui vous facture.

Votre premier clip

L'image-to-video part d'une image fixe. Envoyez-la une fois et gardez l'identifiant :

POST /v1/api/uploads
{ "imageBase64": "<your start frame, base64>" }

-> { "upload": { "id": "..." } }

Puis mettez le clip en file, comme une image :

POST /v1/api/videos
Idempotency-Key: 7f1c2b90-clip-4411

{
  "model": "fellowi-image-to-video-turbo",
  "uploadId": "<id from /v1/api/uploads>",
  "prompt": "steam rises slowly from the mug, the camera drifts in",
  "durationSec": 5,
  "resolution": "720p",
  "generateAudio": false
}

Interrogez GET /v1/api/videos/{id} jusqu'au statut succeeded, puis téléchargez videoUrl. Un clip prend des minutes, pas des secondes : interrogez sans précipitation et prévenez vos utilisateurs. Les modèles text-to-video se passent entièrement d'envoi d'image. Le prix est à la seconde de clip dans la résolution choisie, le son et les images de référence supplémentaires s'ajoutant là où le modèle les accepte. Les clips via l'API se paient toujours en coins ; le quota d'une offre Director ne couvre que les clips faits dans le studio vidéo web.

L'intégrer à un vrai produit

• Gardez la clé sur votre serveur. Ne l'envoyez jamais à un navigateur ou à une application mobile. Votre backend nous appelle, votre front appelle votre backend.
• Traitez-le comme une file de tâches. Stockez l'identifiant de génération avec votre propre enregistrement, interrogez depuis un worker et gardez votre propre copie du fichier dès qu'il arrive. Notre copie sert à la livraison, pas d'archive.
• L'échec est un résultat normal. Une génération échouée rembourse ses coins d'elle-même et renvoie l'un de quatre codes : TIMEOUT, MODERATION_REJECTED, VENDOR_ERROR ou UNKNOWN. Montrez quelque chose d'utile pour chacun et laissez réessayer.
• Respectez la limite de requêtes par clé. C'est une protection contre les abus, pas un quota, et elle s'affiche à côté de chaque clé dans la console. Le vrai plafond, c'est votre solde de coins.

Nous détaillons la tarification et les remboursements dans pourquoi l'API est facturée en coins, et le contenu adulte de la même API dans notre guide de l'API de génération de personnages.

Ce qu'elle ne fait pas

Pas encore de webhooks : vous interrogez. Pas d'offre gratuite : chaque appel coûte des coins, au même prix que dans le studio. Elle ne rendra pas ce que la modération refuse, et le contenu adulte n'a pas sa place sur les plateformes publiques, quelle que soit votre application. Et si nos conditions ne limitent pas l'usage commercial de ce que vous générez, nous ne promettons pas qu'une image soit unique ou libre de tout droit de tiers : traitez-la comme une image de banque que vous n'auriez pas prise vous-même. Si cela convient à ce que vous construisez, la console est le point de départ.