how-tos

Seedance 2.5 API : guide pour appeler Seedance 2.5 Flash avec cURL et Python

Poyo.ai Team
12 min read
Share:

Un coursier à vélo qui fait la course contre une tour d’horloge à l’aube, illustration éditoriale pour le guide de l’API Seedance 2.5 Flash

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émentValeur
Endpoint de soumissionPOST https://api.poyo.ai/api/generate/submit
Endpoint de statutGET https://api.poyo.ai/api/generate/status/{task_id}
En-tête d’authentificationAuthorization: Bearer $POYO_API_KEY
Identifiant de modèleseedance-2.5-flash (le slug de page seedance-2-5-flash n’est pas un identifiant de modèle)
Champs obligatoiresprompt, duration
DuréeSecondes entières, 4–30
Résolution480p ou 720p, 720p par défaut
Format d’imageauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, auto par défaut
Audiogenerate_audio, true par défaut
LivraisonTâ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-Signature sous la forme base64(HMAC-SHA256(task_id + "." + timestamp, key)), avec timestamp tiré de X-Webhook-Timestamp et la clé obtenue via GET /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.

ModeSélectionné quandFormat d’image
Référence-vers-vidéoL’un des champs reference_image_urls, reference_video_urls, reference_audio_urls n’est pas videToute valeur prise en charge
Image-vers-vidéo (première/dernière image)image_urls n’est pas videauto ou omis ; la sortie suit la première image
Texte-vers-vidéoAucun médiaToute 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.

ChampRègle
promptObligatoire, chaîne non vide
durationEntier obligatoire, 4–30
resolution480p ou 720p uniquement ; 1080p nécessite seedance-2.5
aspect_ratioL’une des sept valeurs ; utilisez auto ou omettez-le avec image_urls
image_urls1–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_urlsJusqu’à 10 ; JPEG, PNG ou WebP, jusqu’à 30 Mo chacune
reference_video_urlsJusqu’à 5 ; MP4 ou MOV, 2–30 s et jusqu’à 200 Mo chacune ; durée cumulée de 30 s au plus
reference_audio_urlsJusqu’à 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édiasHTTP 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 :

CodeTypeQue faire
400validation_error, file_format_error, content_moderation_errorCorrigez la requête ou le média ; ne réessayez pas à l’identique
401authentication_errorVérifiez l’en-tête Bearer et que la clé existe toujours
402insufficient_credits_errorRechargez, puis resoumettez
429Limite de débitTemporisez (1 s, 2 s, 4 s...) avant d’interroger ou de soumettre à nouveau
500, 502, 503Serveur ou service en amontRéessayez l’appel de statut avec backoff ; vérifiez le statut avant de resoumettre
Tâche failederror_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-dessusSecondes facturéesCréditsUSD
Test cURL, 5 s 480p592.5$0.4625
Texte-vers-vidéo, 30 s 720p301,230$6.15
Première/dernière image, 5 s 720p5205$1.025
Images + audio de référence, 6 s 480p6111$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.

Share: