Comment utiliser l'API Seedance 2.5 : guide express

Vous pouvez passer de la clé API au MP4 final en quatre étapes : envoyez une requête POST authentifiée, enregistrez le request_id, interrogez le point de terminaison de résultat toutes les 10 à 20 secondes, et téléchargez la vidéo avant l'expiration du lien, souvent dans les 24 heures.

Si je voulais la version courte, voici ce que je garderais à l'esprit :

• Utilisez le bon point de terminaison
  • seedance-2.5-text-to-video pour les prompts texte
  • seedance-2.5-image-to-video pour animer une URL d'image publique
• Envoyez les bons en-têtes
  • Authorization: Bearer <API_KEY>
  • Content-Type: application/json
• Choisissez les principaux réglages de sortie
  • resolution : 480p à 4K
  • aspect_ratio : comme 16:9 ou 9:16
  • duration : jusqu'à 16 secondes
  • generate_audio : true pour le son et les répliques parlées
• Interrogez au lieu de resoumettre
  • Vérifiez predictions/{request_id}/result
  • Surveillez queued, running, succeeded ou failed
• Maîtrisez le coût
  • Commencez à 480p ou 720p
  • Gardez le même seed
  • Relancez à 1080p ou 4K seulement quand le plan est bon

Je surveillerais aussi les points de défaillance les plus courants : 401 pour un mauvais en-tête d'authentification, 402 pour un manque de crédits, 429 pour trop de tâches actives, et 400 pour un JSON invalide ou des champs manquants. Sur APIMart, les crédits sont réservés au démarrage d'une tâche et facturés seulement si elle aboutit ; les tâches échouées sont remboursées.

Si vous choisissez entre les modèles, Seedance 2.5 est l'option haut de gamme de cette gamme : jusqu'à 16 s, jusqu'à 3 840 × 2 160, et jusqu'à 50 entrées de référence. Seedance 2.0 se situe au milieu, et Seedance 2 Mini convient mieux aux ébauches à faible coût.

En résumé : si vous savez faire une requête POST valide et stocker un ID, vous pouvez exécuter tout le flux de travail. Le reste, c'est l'ajustement du prompt, une interrogation patiente et le téléchargement du fichier avant l'expiration de l'URL. Pour le post-traitement, vous pouvez utiliser l'AI Canvas pour agrandir ou éditer vos clips générés.

Étape 1 : configurer l'accès APIMart et authentifier les requêtes

Chaque requête Seedance 2.5 a besoin d'une clé API valide et des bons en-têtes. Commencez par là. Une fois cela en place, vous pouvez passer aux charges utiles de génération vidéo et au suivi des tâches.

Créer et stocker votre clé API en toute sécurité

Créez votre clé dans le tableau de bord du compte sous Settings ou API Keys. Puis stockez-la dans un fichier .env ou une variable d'environnement, pas dans le contrôle de source ^[6][8].

export APIMART_API_KEY="sk_live_xxxxxx"

Si la clé est perdue, révoquez-la et créez-en une nouvelle ^[3]. Pour les tests d'intégration, utilisez une clé sk_test_ séparée afin de ne pas toucher à l'usage de production ^[3].

Ensuite, incluez cette clé dans chaque requête avec l'en-tête Authorization.

Ajouter correctement l'en-tête Authorization

Envoyez les requêtes à https://muapi.ai/api/v1/ avec ces en-têtes :

• Authorization: Bearer sk_live_xxxxxx
• Content-Type: application/json

Un petit écart de formatage peut casser la requête. Le plus courant est d'omettre le préfixe Bearer, ou de manquer l'espace avant la clé ^[3][7]. Cela mène généralement à une réponse 401 Unauthorized. Omettre Content-Type: application/json peut aussi faire échouer la requête ^[3][7].

L'authentification réglée, vous pouvez passer à la charge utile de la requête vidéo.

Étape 2 : construire une requête de génération vidéo Seedance 2.5

Avec votre clé API configurée, le prochain geste est de construire un corps de requête valide. Chaque tâche Seedance 2.5 commence par une requête POST vers l'un de deux points de terminaison, selon votre point de départ. Utilisez https://muapi.ai/api/v1/seedance-2.5-text-to-video pour la génération à partir d'un prompt seul, ou https://muapi.ai/api/v1/seedance-2.5-image-to-video si vous animez une image source ^[1].

Choisir le bon mode d'entrée et les bons paramètres

Votre mode d'entrée détermine la forme de la charge utile. Le texte-vers-vidéo n'a besoin que d'un prompt. L'image-vers-vidéo a aussi besoin d'une image_url qui pointe vers un fichier JPG, PNG ou WEBP accessible publiquement et de moins de 10 Mo ^[1].

À partir de là, vous contrôlez la sortie avec quelques champs principaux :

• resolution : 480p, 720p, 1080p ou 4K
• aspect_ratio : 16:9, 9:16, 1:1, 4:3, 3:4 ou 21:9
• duration : jusqu'à 16 secondes sur Muapi
• generate_audio : un booléen qui active le son ambiant synchronisé, les effets et le dialogue lorsqu'il est réglé sur true ^[1]

Une méthode astucieuse consiste à commencer à 480p avec un seed fixe. Si le mouvement, le rythme et le cadrage sont bons, relancez ce même seed à 1080p ou 4K pour la version finale.

Pour les prompts, utilisez ce flux : Sujet → Action → Caméra → Décor → Ambiance ^[4]. Gardez le mouvement, la direction de caméra et l'ambiance à l'intérieur du prompt lui-même, et laissez le seed inchangé pendant que vous testez des variations. Si vous avez besoin de synchronisation labiale, placez la réplique parlée entre guillemets doubles directement dans la chaîne du prompt. Par exemple : she turns and says "We launch at dawn." Dans ce cas, assurez-vous que generate_audio est réglé sur true ^[1].

Une fois que la charge utile semble bonne, soumettez la tâche et enregistrez l'ID de requête renvoyé. Vous en aurez besoin pour l'interrogation.

Exemples de requêtes en cURL, Postman, Python et JavaScript

Ci-dessous se trouve la même charge utile texte-vers-vidéo présentée dans quatre outils courants.

cURL

curl -X POST https://muapi.ai/api/v1/seedance-2.5-text-to-video \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": true,
    "seed": 42
  }'

Postman - Créez une nouvelle requête POST, collez l'URL du point de terminaison, ajoutez Authorization: Bearer <your_key> et Content-Type: application/json dans l'onglet Headers, puis collez le JSON ci-dessus dans Body → raw → JSON. Cliquez sur Send et enregistrez le request_id de la réponse.

Python

import os, requests

payload = {
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": True,
    "seed": 42
}

response = requests.post(
    "https://muapi.ai/api/v1/seedance-2.5-text-to-video",
    headers={
        "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
        "Content-Type": "application/json"
    },
    json=payload
)

print(response.json())  # save request_id here

JavaScript (fetch)

const response = await fetch("https://muapi.ai/api/v1/seedance-2.5-text-to-video", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    aspect_ratio: "16:9",
    resolution: "1080p",
    duration: 8,
    generate_audio: true,
    seed: 42
  })
});

const data = await response.json();
console.log(data.request_id); // use this to poll for results

Quelques erreurs peuvent vous piéger vite. N'envoyez pas d'image_url qui n'est pas accessible publiquement. Ne cumulez pas des directions de caméra qui se contredisent dans le même prompt. Et en mode image-vers-vidéo, ne redécrivez pas un sujet si l'image source le définit déjà ^[1].

Après la soumission, interrogez le statut de la tâche jusqu'à ce que l'URL du MP4 soit prête.

Quand utiliser Seedance 2.5 dans la gamme de modèles vidéo d'APIMart

Cette comparaison rapide vous aide à choisir le bon modèle avant de commencer à ajuster les prompts ou à augmenter la résolution. Seedance 2.5 vous donne la 4K native, jusqu'à 50 entrées de référence et la prise en charge de clips plus longs. Seedance 2 Mini convient mieux aux ébauches légères, tandis que Seedance 2.0 se situe au milieu comme option d'usage général ^[1][9][4].

Si le projet est un livrable final - comme une vidéo de lancement de produit, une séquence cinématographique de marque, ou tout ce qui est destiné à la diffusion - Seedance 2.5 est le meilleur choix. Pour les projets nécessitant la génération de vidéo IA avec audio de haute qualité, Veo 3.1 de Google est un autre concurrent solide. Si vous testez encore des idées, commencez avec Mini pour vérifier le mouvement et figer le cadrage à moindre coût, puis passez à la 2.5 pour le rendu final.

Étape 3 : soumettre la tâche, suivre le statut et lire la réponse

Une fois que vous envoyez la requête POST, l'API renvoie un request_id. Enregistrez-le. Vous utiliserez cet ID pour vérifier la tâche plus tard, car la génération s'exécute de façon asynchrone.

Gérer les tâches asynchrones de la création à la complétion

Après avoir soumis la tâche, l'étape suivante est simple : interroger jusqu'à ce que la vidéo finale soit prête.

Envoyez une requête GET à https://muapi.ai/api/v1/predictions/{request_id}/result. Attendez environ 10 secondes après la soumission avant la première interrogation, puis vérifiez à nouveau toutes les 10 à 20 secondes. Si vous interrogez plus souvent que toutes les 5 secondes, vous risquez d'atteindre les limites de débit ^[1][3].

Chaque réponse inclut un champ status. Ce champ vous indique ce qui se passe et ce que vous devez faire ensuite :

Une fois que la tâche atteint succeeded, saisissez l'URL de sortie avant qu'elle n'expire.

Lire les champs de sortie et enregistrer les résultats

Quand le statut passe à succeeded, lisez la charge utile de sortie et stockez le résultat.

Une réponse réussie inclut video_url. Elle peut aussi inclure last_frame_url si vous l'avez demandé. Enregistrez video_url, l'optionnel last_frame_url, et des métadonnées comme seed, duration, resolution, aspect_ratio et usage. Ces données comptent pour la facturation et pour reproduire la même exécution plus tard ^[11][13].

Les URL de sortie expirent souvent dans les 24 heures, donc téléchargez le fichier vers votre propre stockage tout de suite ^[11][12][13]. Si une tâche échoue, journalisez error.code et error.message. Et si l'échec est lié à des vérifications de sécurité, ne la réessayez pas automatiquement ^[2][11][12].

Étape 4 : dépanner les erreurs, maîtriser le coût et conclure

Corriger les erreurs d'authentification, de validation et de limite de débit

Après avoir soumis une tâche et interrogé les résultats, quelques vérifications simples peuvent empêcher les exécutions de production de dérailler. La plupart des échecs de Seedance tendent à se manifester des mêmes quelques façons.

Pour les ressources de référence, assurez-vous que l'URL est publique, que le fichier est en JPG, PNG ou WEBP, et qu'il reste sous la limite de taille indiquée ^[12][4].

Réduire les coûts et améliorer la fiabilité

Une fois la gestion des erreurs en place, l'étape suivante est simple : testez à bas coût, puis rendez en grand.

Commencez votre prompt à 480p ou 720p. Cela vous donne un moyen peu coûteux de vérifier le cadrage, le mouvement et si le prompt fait ce que vous voulez. Si le plan est bon, relancez la même valeur seed en 4K pour la sortie finale ^[1][4].

La durée du clip compte aussi. Les vidéos plus courtes coûtent moins cher, donc gardez la durée au minimum qui fait encore le travail ^[1][10].

Il y a aussi une façon sournoise pour les équipes de gaspiller de l'argent : les soumissions en double après un délai d'expiration réseau. Une correction propre consiste à hacher le prompt, l'ID du modèle et les URL des médias avant chaque requête POST. Si ce hachage correspond déjà à un ID de tâche, sautez complètement la nouvelle soumission ^[11]. Et une fois qu'une tâche atteint succeeded, enregistrez le fichier fini dans un stockage durable pour ne pas dépendre de l'enregistrement de tâche plus tard ^[12][11].

Conclusion : de la doc API à une génération vidéo qui marche

Avec l'authentification, les charges utiles, l'interrogation et la gestion des erreurs en place, vous disposez maintenant d'un flux de travail Seedance 2.5 complet sur APIMart.

FAQ

Combien de temps Seedance 2.5 met-il pour finir une vidéo ?

Seedance 2.5 peut générer un clip vidéo continu jusqu'à 30 secondes de long. La doc, cependant, ne liste pas de durée de finition exacte.

L'API s'exécute de façon asynchrone. Vous soumettez une tâche, obtenez un ID de tâche, puis vous interrogez le point de terminaison de statut ou attendez un webhook pour obtenir la vidéo finie.

Le temps de traitement peut varier selon des facteurs comme la résolution et la complexité de la scène.

Que faire si mon URL de vidéo expire avant que je la télécharge ?

Si votre URL de vidéo expire avant que vous la téléchargiez, vous ne pourrez pas obtenir le fichier depuis ce lien. Seedance garde ces URL temporaires actives pendant 24 heures.

Le geste sûr est simple : copiez la vidéo vers votre propre stockage objet sécurisé dès que la tâche s'affiche comme terminée. Parce que l'API s'exécute de façon asynchrone et ne conserve pas la sortie éternellement, votre application devrait récupérer la vidéo et la déplacer vers un stockage à long terme tout de suite.

Comment éviter les frais en double lors de la relance de requêtes échouées ?

Utilisez une gestion de requête idempotente liée à vos propres enregistrements de tâche durables, pas seulement au client HTTP.

Avant de soumettre quoi que ce soit, construisez un hachage de requête déterministe à partir d'entrées comme le prompt, l'ID du modèle, les ID des ressources et l'identifiant utilisateur. Puis enregistrez ce hachage avec un statut submitting dans votre propre base de données.

Si ce même hachage réapparaît, renvoyez la tâche existante au lieu d'en créer une nouvelle.

Une fois que vous avez stocké un ID de tâche fournisseur, ne resoumettez pas la requête. Reprenez simplement l'interrogation avec cet ID de tâche.