Tutoriel : transformer une image en vidéo

Avoir un compte, un solde et une clé API

Suivez d’abord Préparer votre compte. À la fin, vous devez avoir :

• un compte SpicyAPI dont le solde est approvisionné ;
• une clé API, qui commence par sk-spicy- ;
• cette clé enregistrée dans une variable d’environnement nommée SPICY_API_KEY. Une variable d’environnement est une valeur nommée que votre terminal transmet aux programmes qu’il lance : la clé n’a ainsi jamais besoin d’apparaître dans une commande ni dans votre code.

Vérifiez que la clé est bien définie dans la fenêtre de terminal que vous utilisez, sans afficher la clé entière :

echo "${SPICY_API_KEY:0:9}"

Ce que vous devez voir : sk-spicy-. Si rien ne s’affiche ou si une erreur apparaît, la clé n’est pas définie dans cette fenêtre ; revenez à Préparer votre compte.

Placer votre image dans un dossier de travail

Créez un dossier pour ce tutoriel et ouvrez votre terminal dedans. Toutes les commandes de cette page s’exécutent depuis ce dossier, et tous les fichiers qu’elles créent y atterrissent.

mkdir -p ~/spicy-video
cd ~/spicy-video

Copiez votre image dans ce dossier et nommez-la start-frame.jpg (ou start-frame.png s’il s’agit d’un PNG ; utilisez alors ce nom partout où cette page écrit start-frame.jpg).

Ce qui fait une bonne image de départ :

• Format et taille : JPEG, PNG, WebP ou GIF, jusqu’à 10 MiB (environ 10 mégaoctets). Un modèle peut fixer ses propres limites, plus strictes ; vous les verrez à l’étape 1.
• Le fichier doit vraiment être dans ce format. SpicyAPI examine le contenu du fichier, pas seulement son nom. Les photos prises au téléphone sont souvent en HEIC ; renommer l’une d’elles en .jpg ne la convertit pas. Ouvrez-la d’abord et exportez-la ou enregistrez-la en JPEG.
• Cadrage : l’image devient la première image de la vidéo. Prenez une image large pour une vidéo large et une image en hauteur pour une vidéo verticale ; certains modèles proposent aussi un réglage aspect_ratio.
• Droits : utilisez une image que vous avez le droit d’utiliser.

Installer l’outil choisi

npm install -g @spicyapi/cli
spicyapi --version

spicyapi balance

1. Choisir un modèle et lire ses réglages

À faire : listez les modèles image vers vidéo que votre compte peut utiliser, choisissez-en un, puis lisez les réglages qu’il accepte.

spicyapi models list --modality video --task image-to-video --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example video model",
      "modality": "video",
      "tasks": ["image-to-video"],
      "enabled": true,
      "available": true,
      "quantityField": "duration_seconds",
      "maxOutputDurationSeconds": 10,
      "taskTimeoutSeconds": 1800,
      "pricing": [
        { "variant": "720p", "unit": "per_second", "price": "…", "currency": "USD" },
        { "variant": "1080p", "unit": "per_second", "price": "…", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

Ce qu’il faut regarder dans la liste :

Comment lire les réglages. inputSchema est la liste des réglages du modèle, écrite en JSON Schema :

• required liste les réglages que vous devez obligatoirement envoyer. Pour ce type de modèle, image_url en fait toujours partie, et la plupart exigent aussi prompt.
• properties liste tous les réglages que le modèle accepte, chacun avec un type, une description en anglais courant et, souvent, enum (les seules valeurs autorisées), minimum et maximum, et default (la valeur utilisée si vous omettez le réglage).
• Dans chaque réglage, x-ui contient des indications d’affichage. x-ui.affects_price: true signifie que modifier ce réglage modifie le prix.
• Quelques modèles ajoutent des conditions au niveau supérieur, comme « si vous envoyez A, vous devez aussi envoyer B ». Spicy Schema explique comment les lire.
• examples contient des entrées complètes déjà validées par le serveur : un point de départ sûr.

Les réglages que vous croiserez le plus souvent. Les noms sont les mêmes pour tous les modèles, mais chaque modèle n’en accepte qu’une partie, avec ses propres valeurs autorisées :

Ce qui s’est passé : vous avez lu le catalogue en direct de votre compte, avec vos prix. Rien n’a été facturé. La lecture du catalogue compte dans la limite de débit de votre compte : inutile donc de la refaire avant chaque vidéo ; recommencez quand vous changez de modèle ou recevez un 400.

2. Téléverser votre image

À faire : téléversez start-frame.jpg et copiez l’adresse spicy:// que vous recevez en retour. Le téléversement est gratuit.

spicyapi files upload start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z

Ce qui s’est passé : votre image a été stockée de façon privée pour votre compte, vérifiée (son format réel doit correspondre au type déclaré) et dotée d’une adresse spicy://. Cette adresse n’est pas un lien web : seul votre compte peut l’utiliser, et uniquement dans l’entrée d’une tâche. Elle est utilisable pendant un jour (voir expiresAt) ; passé ce délai, téléversez l’image de nouveau.

Si le téléversement échoue :

3. Décrire la vidéo et vérifier le prix

À faire : écrivez vos réglages dans un fichier nommé input.json, puis demandez un devis.

Écrire input.json. Commencez par les deux réglages que tout modèle image vers vidéo accepte. Mettez votre propre phrase dans prompt, et remplacez la valeur de image_url par l’uri copiée à l’étape 2 :

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}

Les réglages que vous omettez prennent la valeur default du modèle. Pour les choisir vous-même, ajoutez uniquement des réglages listés dans les properties de votre modèle, avec des valeurs qu’il autorise. Par exemple, si votre modèle liste duration_seconds et resolution et autorise ces valeurs :

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5,
  "resolution": "720p"
}

Enregistrez le fichier dans votre dossier de travail :

cat > input.json <<'EOF'
{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}
EOF

Utilisez des guillemets droits ordinaires ("), pas des guillemets courbes, et ne mettez pas de virgule après le dernier réglage.

Obtenir le devis :

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: …
maxCharge: …
currency: USD
quantity: 5
unit: per_second
expiresAt: 2026-09-17T08:05:00Z

Ce qui s’est passé : SpicyAPI a contrôlé votre entrée par rapport aux réglages du modèle et calculé le prix de cette requête précise. Rien n’a été lancé et rien n’a été facturé. estimatedCost est le montant qui sera mis de côté si vous lancez la génération maintenant, et maxCharge le maximum qu’elle peut coûter. quantity et unit indiquent ce que vous payez, par exemple 5 secondes.

Un devis est valable cinq minutes, et uniquement pour cette entrée exacte. Changez la durée ou la résolution et redemandez un devis pour comparer les prix. Le devis effectue les mêmes contrôles que le lancement de la tâche : les problèmes apparaissent donc ici, gratuitement. Un 400 signifie que l’entrée ne correspond pas aux réglages du modèle (corrigez input.json à l’aide de l’étape 1), et un 40201 que votre solde ne suffirait pas. L’étape 7 liste les autres codes.

4. Lancer la génération

La clé d’idempotence, en termes simples. C’est une étiquette pour une vidéo, comme un numéro de commande. Si votre connexion coupe et que vous ne savez pas si la vidéo a démarré, renvoyez la même requête avec la même étiquette : SpicyAPI vous rend la tâche déjà lancée au lieu d’en lancer, et d’en facturer, une seconde. Une étiquette reste valable 24 heures avec la même clé API. Prenez une nouvelle étiquette pour une autre vidéo : la même étiquette avec une entrée différente est refusée avec 409. Pour en savoir plus : Idempotence.

À faire :

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json

Estimated charge: USD …; maximum charge: USD …. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? … Continue? [y/N]

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
taskId: job_01k3m8x9q2z4v7n5p6r8s0t1w3
state: queued
estimatedCost: …
deadlineAt: 2026-09-17T08:35:00Z

Ce qui s’est passé : SpicyAPI a accepté la génération, qui est désormais une tâche, et a mis estimatedCost de côté sur votre solde. C’est aussi le maximum que cette vidéo peut coûter. state: queued signifie qu’elle attend son tour. deadlineAt est l’heure limite à laquelle elle peut se terminer ; si elle n’est pas finie à ce moment-là, elle se termine en expired et rien n’est facturé. deadlineAt n’est pas la date d’expiration de vos fichiers.

Transmettre le devis revient à dire « n’accepte cette tâche qu’au prix qu’on m’a montré ». Si le prix ou l’entrée a changé entre-temps, la requête est refusée avec 40901 au lieu de mettre de côté un autre montant. La CLI s’en charge pour vous.

Si la connexion a coupé et que vous n’avez jamais vu d’identifiant de tâche, ne relancez pas simplement avec une nouvelle étiquette : cela créerait, et facturerait, une seconde vidéo. Renvoyez la requête avec la même étiquette :

• CLI : spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key <the value you copied>, en remplaçant <the value you copied> par la valeur Idempotency-Key que vous avez copiée. Voir Reprendre une tâche après une attente interrompue.
• SDK : relancez node generate.mjs --yes ; il réutilise idempotency-key.txt.
• HTTP : relancez le bloc « Lancer la vidéo » ; il réutilise idempotency-key.txt.

Si l’étape 4 a été refusée, rien n’a été créé et rien n’a été facturé ; la raison et la solution se trouvent à l’étape 7.

5. Attendre la vidéo

À faire : consultez la tâche jusqu’à ce qu’elle soit terminée. Une vidéo prend généralement quelques minutes.

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000 --json

{
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "state": "succeeded",
  "output": {
    "assets": [
      {
        "key": "tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4",
        "url": "https://…",
        "expiresAt": "2026-09-17T08:40:00Z",
        "mime": "video/mp4",
        "durationSeconds": 5,
        "width": 1280,
        "height": 720,
        "bytes": 4839211
      }
    ]
  },
  "cost": "…",
  "settled": true
}

Ce qui s’est passé : votre outil a interrogé SpicyAPI sur la tâche toutes les quelques secondes. Les états sont queued (en attente), running (en cours de génération), puis un état final : succeeded, failed ou expired. Après un succès, le fichier est copié dans le stockage propre à SpicyAPI, ce qui prend encore quelques secondes ; en attendant, le résultat affiche pending: true. cost est définitif une fois que settled vaut true.

• Fermer le terminal ou appuyer sur Ctrl + C n’annule pas la tâche. Cela arrête seulement l’attente. Gardez l’identifiant de la tâche et refaites cette étape plus tard.
• Ne vérifiez pas plus souvent que toutes les quelques secondes. Consulter une tâche utilise le quota de lecture du compte, indépendamment du lancement de tâches ; voir Limites de débit.
• Pour une application ou un serveur, laissez SpicyAPI vous prévenir quand la tâche est terminée au lieu de poser la question : voir Être prévenu au lieu d’attendre.

6. Télécharger et conserver la vidéo

À faire : obtenez un lien de téléchargement récent et enregistrez le fichier sur votre ordinateur.

spicyapi files download-url job_01k3m8x9q2z4v7n5p6r8s0t1w3

key: tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4
url: https://…
expiresAt: 2026-09-17T08:52:00Z

curl -L -o my-video.mp4 "PASTE_THE_URL_HERE"

Ce qui s’est passé : chaque résultat est fourni avec un lien de téléchargement direct. Ce lien fonctionne environ 20 minutes et ne demande pas de clé API ; n’y ajoutez jamais votre clé. Quand il a expiré, redemandez la tâche (ou utilisez files download-url) pour en obtenir un nouveau.

7. En cas de problème

Les problèmes sont de deux sortes, et ils ne se traitent pas de la même façon.

Une requête est refusée. Votre commande ou votre appel reçoit immédiatement une erreur. Rien n’a été créé et rien n’a été facturé. Le message explique pourquoi, et l’erreur comporte un code et un identifiant de requête (req_…) à citer si vous contactez l’assistance.

La tâche échoue. La tâche a été acceptée, mais se termine en failed ou expired au lieu de succeeded. La tâche affiche un errorCode qui en donne la raison, et un errorMessage qui l’explique plus en détail. Les tâches échouées ou expirées libèrent normalement toute la réservation. Certains refus de contenu sont facturés au devis accepté, uniquement si la page du modèle indique explicitement cette exception. Consultez settled et cost pour connaître le montant final.

Pour le lire :

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Décidez ensuite quoi faire d’après l’errorCode, et non d’après la formulation du message :

Traitez toute autre valeur comme upstream_failed. La liste complète se trouve dans Erreurs.

Relancer une tâche échouée. Une relance crée une nouvelle tâche avec le même modèle et la même entrée, au prix actuel du modèle. Elle coûte de l’argent, comme l’étape 4, et elle reprend l’entrée d’origine : si cette entrée utilisait un téléversement qui a expiré depuis, téléversez de nouveau et lancez plutôt une nouvelle tâche.

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait --wait-timeout-ms 1800000

Seules les tâches failed et expired peuvent être relancées. Pour obtenir une autre version d’une vidéo réussie, revenez à l’étape 3 avec une nouvelle étiquette. Une tâche acceptée ne peut en aucun cas être annulée. Pour en savoir plus : Engagement et relance.