Génération de vidéos

POST /v1/videos · GET /v1/videos/{id} · DELETE /v1/videos/{id}

Générez de courtes vidéos à partir d'un prompt texte, éventuellement guidées par des frames de référence (première/dernière). C'est une API de jobs asynchrones au format standard create + poll : POST /v1/videos crée une tâche qui répond en ~2 secondes, vous la sondez jusqu'à la fin, et l'en-tête Prefer: wait transforme les générations rapides en un seul appel synchrone. Modèles Seedance, une seule clé API, la même facturation que les autres endpoints.

Endpoints et cycle de vie d'une tâche

Une ressource tâche, quatre opérations. Une tâche passe de queued → in_progress → un état terminal : completed, failed ou cancelled. La réponse de création inclut des liens status_url / cancel_url prêts à l'emploi — vous n'assemblez jamais d'URL à la main.

Sucre synchrone — Prefer: wait

Ajoutez un en-tête Prefer: wait ou Prefer: wait=N (N borné à 1..60 secondes) à l'appel de création et la passerelle garde la requête ouverte. Si la tâche se termine dans la fenêtre, vous recevez directement l'objet terminal — URL de la vidéo et usage inclus, sans polling. Sinon, l'appel se dégrade proprement : vous recevez l'objet d'état courant (pas d'erreur, la tâche continue) et poursuivez avec le polling normal.

Corps de la requête

Modèles disponibles

La disponibilité des modèles dépend de votre déploiement. Récupérez la liste en direct, sensible à la conformité — avec les contraintes de résolution/durée et les prix de chaque modèle — via GET /v1/videos/models. La gamme actuelle :

Prix : USD par 1M de video tokens. seedance-1-5-pro-251215 facture $2.4 avec la piste audio activée (generate_audio: true, le défaut) et $1.2 sans ; les autres modèles ont un tarif unique par palier de résolution.

Video tokens et tarification

La vidéo est facturée en video tokens, dérivés de la sortie réelle : tokens ≈ largeur × hauteur × 24 fps × secondes / 1024. Les tarifs sont par 1M de video tokens et suivent les paramètres réellement appliqués (renvoyés dans la tâche completed) — ratio: "adaptive" et duration: -1 sont donc facturés selon ce que le modèle a réellement produit.

Repères concrets sur seedance-1-5-pro-251215 avec audio : un clip 480p / 16:9 / 4 s ≈ 40,6K video tokens ≈ $0.10 ; un clip 720p / 5 s ≈ 108,9K tokens ≈ $0.26.

Facturation

Facturé uniquement en cas de succès : le débit a lieu une seule fois, quand la tâche atteint completed pour la première fois, au prorata de l'usage en video tokens renvoyé. Les tâches échouées (y compris les rejets de modération de contenu) et annulées ne sont jamais facturées — l'erreur du fournisseur est transmise telle quelle.

Exemple — curl, en un coup (Prefer: wait)

curl https://synthorai.io/v1/videos \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{
    "model": "seedance-1-0-pro-fast-251015",
    "prompt": "A corgi puppy chasing a butterfly across a meadow, cinematic",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4
  }'

# Finished inside the wait window → the terminal object comes straight back:
{
  "id": "vid_6091d8d1af805818b1470488",
  "object": "video",
  "model": "seedance-1-0-pro-fast-251015",
  "status": "completed",
  "data": [{ "url": "https://…tos….mp4?…" }],
  "usage": { "completion_tokens": 40594, "total_tokens": 40594 },
  "resolution": "480p", "ratio": "16:9", "duration": 4, "fps": 24,
  "seed": 34142
}
# Not done in time → the current status object is returned instead (no error,
# the task keeps running) — continue polling status_url as usual.

Exemple — curl, create + poll

# 1) Create — returns in ~2 s with a queued task object
curl https://synthorai.io/v1/videos \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1-5-pro-251215",
    "prompt": "A corgi puppy chasing a butterfly across a meadow, cinematic",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  }'

{
  "id": "vid_6091d8d1af805818b1470488",
  "object": "video",
  "model": "seedance-1-5-pro-251215",
  "status": "queued",
  "created_at": 1784619862,
  "status_url": "https://synthorai.io/v1/videos/vid_6091d8d1af805818b1470488",
  "cancel_url": "https://synthorai.io/v1/videos/vid_6091d8d1af805818b1470488"
}

# 2) Poll until status is terminal (completed | failed | cancelled)
curl https://synthorai.io/v1/videos/vid_6091d8d1af805818b1470488 \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY"

{
  "id": "vid_6091d8d1af805818b1470488",
  "object": "video",
  "model": "seedance-1-5-pro-251215",
  "status": "completed",
  "data": [{ "url": "https://…tos….mp4?…" }],
  "usage": { "completion_tokens": 108900, "total_tokens": 108900 },
  "resolution": "720p", "ratio": "16:9", "duration": 5, "fps": 24,
  "seed": 34142, "generate_audio": true
}

# 3) Download the video — the URL is pre-signed (no auth header) and expires
#    in ~24 h: fetch promptly and re-host if you need it long-term.
curl -o out.mp4 "https://…tos….mp4?…"

Exemple — Python (requests)

import time
import requests

BASE = "https://synthorai.io/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

task = requests.post(f"{BASE}/videos", headers=HEADERS, json={
    "model": "seedance-1-5-pro-251215",
    "prompt": "A corgi puppy chasing a butterfly across a meadow, cinematic",
    "resolution": "720p",
    "duration": 5,
}).json()

while task["status"] not in ("completed", "failed", "cancelled"):
    time.sleep(5)
    task = requests.get(task["status_url"], headers=HEADERS).json()

if task["status"] == "completed":
    url = task["data"][0]["url"]  # pre-signed, valid ~24 h — re-host promptly
    with open("out.mp4", "wb") as f:
        f.write(requests.get(url).content)
else:
    print(task["error"])  # provider code + message, passed through verbatim

Exemple — Node (fetch)

import fs from "node:fs";

const BASE = "https://synthorai.io/v1";
const HEADERS = { Authorization: `Bearer ${process.env.SYNTHORAI_API_KEY}` };

let task = await (await fetch(`${BASE}/videos`, {
  method: "POST",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "seedance-1-5-pro-251215",
    prompt: "A corgi puppy chasing a butterfly across a meadow, cinematic",
    resolution: "720p",
    duration: 5,
  }),
})).json();

while (!["completed", "failed", "cancelled"].includes(task.status)) {
  await new Promise((r) => setTimeout(r, 5000));
  task = await (await fetch(task.status_url, { headers: HEADERS })).json();
}

if (task.status === "completed") {
  const url = task.data[0].url; // pre-signed, valid ~24 h — re-host promptly
  fs.writeFileSync("out.mp4", Buffer.from(await (await fetch(url)).arrayBuffer()));
} else {
  console.error(task.error); // provider code + message, passed through verbatim
}

Idempotence

Passez un en-tête X-Idempotency-Key sur l'appel de création pour sécuriser les retries : une requête répétée avec la même clé renvoie 409 au lieu de créer (et facturer) une seconde tâche. La génération vidéo est lente et sujette aux retries — cela évite les doubles débits.