
La Seedance 2.5 Flash API est le niveau plus rapide et moins coûteux de la Seedance 2.5 API ; sur PoYo, elle correspond à un seul identifiant de modèle : seedance-2.5-flash. ByteDance l’a lancée le 12 novembre 2026 ; la page du modèle Seedance 2.5 Flash propose le playground et les prix en vigueur. Ce guide vous mène d’une première requête cURL à une boucle de production en Python, en suivant le schéma de la documentation de l’API Seedance 2.5 Flash tel que vérifié le 16 novembre 2026.
La Seedance 2.5 Flash API en bref
| Élément | Valeur |
|---|---|
| Endpoint de soumission | POST https://api.poyo.ai/api/generate/submit |
| Endpoint de statut | GET https://api.poyo.ai/api/generate/status/{task_id} |
| En-tête d’authentification | Authorization: Bearer $POYO_API_KEY |
| Identifiant de modèle | seedance-2.5-flash (le slug de page seedance-2-5-flash n’est pas un identifiant de modèle) |
| Champs obligatoires | prompt, duration |
| Durée | Secondes entières, 4–30 |
| Résolution | 480p ou 720p, 720p par défaut |
| Format d’image | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, auto par défaut |
| Audio | generate_audio, true par défaut |
| Livraison | Tâche asynchrone : interrogez le statut ou définissez callback_url |
Votre première requête à la Seedance 2.5 API avec cURL
Exportez votre clé dans POYO_API_KEY et conservez-la sur le serveur, jamais dans du code navigateur. Voici une requête texte-vers-vidéo de 5 secondes en 480p, un premier test peu coûteux à 92,5 crédits :
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}'
Une soumission réussie renvoie code: 200 et un objet data contenant task_id, status (toujours not_started juste après la soumission) et created_time. C’est un accusé de réception, pas une vidéo. Enregistrez le task_id, puis interrogez-le :
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Les statuts passent par not_started, running, finished et failed. Quand la tâche est finished, l’URL de la vidéo se trouve dans data.files[].file_url avec file_type: "video" ; en cas de failed, lisez data.error_message. Les fichiers générés restent accessibles 3 jours : copiez-les donc dans votre propre stockage.
Python : soumettre et interroger avec une échéance stricte
La documentation des statuts recommande d’interroger toutes les 2 à 5 secondes, de temporiser en cas de 429 et de 5xx, et de toujours définir un délai d’expiration. La boucle ci-dessous fait les trois et ne resoumet jamais la requête en cas d’expiration, car une seconde soumission est une seconde tâche facturable.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
try:
body = response.json()
except ValueError:
response.raise_for_status()
raise
if body.get("code") != 200:
err = body.get("error") or {}
raise RuntimeError(
f"PoYo {body.get('code')} {err.get('type')}: "
f"{err.get('message') or body.get('detail')}"
)
return body["data"]
task = checked(session.post(BASE + "/api/generate/submit", json={
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9",
},
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)
deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
if r.status_code == 429 or r.status_code >= 500:
time.sleep(backoff)
backoff = min(backoff * 2, 60)
continue
data = checked(r)
if data["status"] == "failed":
raise RuntimeError(data.get("error_message") or "Generation failed")
if data["status"] == "finished":
videos = [f["file_url"] for f in data.get("files", [])
if f.get("file_type") == "video"]
print(videos[0], "credits:", data.get("credits_amount"))
break
backoff = 5
time.sleep(5)
else:
raise TimeoutError("Still running; poll the saved task ID later: " + task_id)
À titre indicatif, lors des tests de PoYo du 16 novembre 2026, un clip de 4 secondes en 480p s’est terminé en environ deux minutes et un clip de 30 secondes en 720p en moins de trois minutes, de bout en bout. Les durées varient selon la charge : l’échéance de 15 minutes est donc une limite de sécurité, pas une estimation.
Se passer de l’interrogation : utiliser callback_url
Ajoutez un callback_url au niveau supérieur, à côté de model. Quand la tâche passe à finished ou failed, PoYo envoie un POST dont le corps est l’objet de données de la tâche (task_id, status, files, created_time, error_message), sans l’enveloppe code/data. D’après la documentation des webhooks vidéo :
- L’URL doit être en HTTPS public, faire au plus 2048 caractères et ne pas pointer vers une IP privée.
- Répondez par un 2xx dans les 30 secondes ; les livraisons échouées sont retentées jusqu’à 5 fois avec un backoff exponentiel.
- Vérifiez
X-Webhook-Signaturesous la formebase64(HMAC-SHA256(task_id + "." + timestamp, key)), avectimestamptiré deX-Webhook-Timestampet la clé obtenue viaGET /api/api-keys/webhook-secret. - Rendez le gestionnaire idempotent. Si toutes les tentatives échouent, l’endpoint de statut conserve le résultat.
Les trois modes d’entrée, avec leurs corps JSON
L’API choisit le mode en fonction des médias envoyés. Il n’existe pas de champ mode.
| Mode | Sélectionné quand | Format d’image |
|---|---|---|
| Référence-vers-vidéo | L’un des champs reference_image_urls, reference_video_urls, reference_audio_urls n’est pas vide | Toute valeur prise en charge |
| Image-vers-vidéo (première/dernière image) | image_urls n’est pas vide | auto ou omis ; la sortie suit la première image |
| Texte-vers-vidéo | Aucun média | Toute valeur prise en charge |
image_urls et les champs de référence s’envoient dans des requêtes distinctes. Ces corps sont les exemples documentés.
Texte-vers-vidéo (30 secondes en 720p, avec une liste de plans minutée dans le prompt) :
{
"model": "seedance-2.5-flash",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
"duration": 30,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}
}
Première et dernière image (une URL fixe l’ouverture ; une seconde fixe la fin) :
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
"image_urls": [
"https://example.com/first-frame.jpg",
"https://example.com/last-frame.jpg"
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto"
}
}
Référence-vers-vidéo (désignez les fichiers par ordre d’envoi : @Image1, @Video1, @Audio1) :
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
"reference_image_urls": [
"https://example.com/cat.png",
"https://example.com/scarf.png",
"https://example.com/bookstore.png"
],
"reference_audio_urls": [
"https://example.com/rhythm.mp3"
],
"duration": 6,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}
Les règles de validation à appliquer avant la soumission
Les vérifier côté client épargne un aller-retour et donne à vos utilisateurs un message plus clair qu’un 400 générique.
| Champ | Règle |
|---|---|
prompt | Obligatoire, chaîne non vide |
duration | Entier obligatoire, 4–30 |
resolution | 480p ou 720p uniquement ; 1080p nécessite seedance-2.5 |
aspect_ratio | L’une des sept valeurs ; utilisez auto ou omettez-le avec image_urls |
image_urls | 1–2 URL (première, puis dernière image) ; JPEG, PNG ou WebP, jusqu’à 30 Mo chacune ; non combinable avec les champs de référence |
reference_image_urls | Jusqu’à 10 ; JPEG, PNG ou WebP, jusqu’à 30 Mo chacune |
reference_video_urls | Jusqu’à 5 ; MP4 ou MOV, 2–30 s et jusqu’à 200 Mo chacune ; durée cumulée de 30 s au plus |
reference_audio_urls | Jusqu’à 5 ; MP3 ou WAV, 2–30 s et jusqu’à 15 Mo chacune ; durée cumulée de 30 s au plus ; nécessite une image ou une vidéo de référence |
| Toutes les URL de médias | HTTP ou HTTPS publics, téléchargeables directement (pas de pages de connexion ni d’aperçus qui expirent) |
Les durées cumulées des références sont vérifiées à la soumission de la tâche. Le schéma définit aussi additionalProperties: false sur input : n’envoyez donc pas de champs issus des API d’autres fournisseurs, comme seed ou negative_prompt.
Les erreurs à gérer
Lisez toujours le champ code du corps : certaines erreurs de validation de l’endpoint de soumission reviennent avec un HTTP 200 et "code": 400. La référence des codes d’erreur liste les cas suivants :
| Code | Type | Que faire |
|---|---|---|
400 | validation_error, file_format_error, content_moderation_error | Corrigez la requête ou le média ; ne réessayez pas à l’identique |
401 | authentication_error | Vérifiez l’en-tête Bearer et que la clé existe toujours |
402 | insufficient_credits_error | Rechargez, puis resoumettez |
429 | Limite de débit | Temporisez (1 s, 2 s, 4 s...) avant d’interroger ou de soumettre à nouveau |
500, 502, 503 | Serveur ou service en amont | Réessayez l’appel de statut avec backoff ; vérifiez le statut avant de resoumettre |
Tâche failed | error_message renseigné | Journalisez l’identifiant de tâche ; les tâches échouées indiquent credits_amount: 0 |
Comment la première facture est calculée
Sans vidéo de référence, le coût est égal aux secondes de sortie multipliées par le tarif à la seconde : 18,5 crédits (0,0925 $) en 480p, 41 crédits (0,205 $) en 720p, avec 1 crédit = 0,005 $. L’audio généré n’ajoute rien.
| Requête ci-dessus | Secondes facturées | Crédits | USD |
|---|---|---|---|
| Test cURL, 5 s 480p | 5 | 92.5 | $0.4625 |
| Texte-vers-vidéo, 30 s 720p | 30 | 1,230 | $6.15 |
| Première/dernière image, 5 s 720p | 5 | 205 | $1.025 |
| Images + audio de référence, 6 s 480p | 6 | 111 | $0.555 |
Ajouter des reference_video_urls fait basculer vers le tarif avec vidéo, plus bas (11,5 crédits en 480p, 25,5 en 720p), appliqué aux secondes facturées : la durée de sortie plus la durée de chaque vidéo de référence arrondie à la seconde entière inférieure. Le détail des prix de la Seedance 2.5 API passe ces cas en revue. Le montant facturé pour une tâche terminée apparaît dans credits_amount dans la réponse de statut.
Passer à Seedance 2.5 pour la 1080p
Les champs de requête sont les mêmes : passer une tâche de Flash au modèle Seedance 2.5 standard revient à changer l’identifiant de modèle :
{
"model": "seedance-2.5",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9"
}
}
Deux précisions : la documentation de seedance-2.5 indique resolution comme obligatoire, envoyez-le donc toujours, et le modèle standard accepte jusqu’à 30 images, 10 vidéos et 10 références audio. En 1080p, il coûte 114 crédits (0,57 $) par seconde. Pour la décision de routage, voir Seedance 2.5 Flash vs Seedance 2.5 ; pour comparer Seedance 2.5 au modèle d’un autre fournisseur, voir Kling 4.0 vs Seedance 2.5.
Questions fréquentes
Quel est l’identifiant de modèle de la Seedance 2.5 Flash API ? seedance-2.5-flash, avec des points. La forme avec tirets seedance-2-5-flash n’est que le slug de la page du modèle.
La Seedance 2.5 Flash API prend-elle en charge la 1080p ? Non. Elle accepte 480p et 720p. Envoyez le même corps avec "model": "seedance-2.5" et "resolution": "1080p" pour obtenir de la 1080p native.
Comment désactiver l’audio dans la Seedance 2.5 API ? Définissez "generate_audio": false pour un clip muet, ou laissez l’audio activé et supprimez certaines couches dans le prompt, par exemple « no background music ».
Puis-je utiliser des premières images et des images de référence dans une même requête Seedance 2.5 Flash ? Non. image_urls et les champs reference_* doivent être envoyés dans des requêtes distinctes.
Combien de temps prend une tâche de la Seedance 2.5 Flash API ? Lors du test de PoYo du 16 novembre 2026, environ deux minutes pour 4 secondes en 480p et moins de trois minutes pour 30 secondes en 720p, de bout en bout. Interrogez le statut ou utilisez un callback plutôt que de garder une requête ouverte.
Suis-je facturé si une tâche Seedance 2.5 Flash échoue ? Non. Les tâches échouées ne sont pas facturées et leur statut indique credits_amount: 0.