Guide d'intégration de l'API Seedance 1.5 Pro via EvoLink : tâches asynchrones, rappels et modes

Ce que vous apprendrez

• Déployer Seedance 1.5 Pro via l'API de tâches asynchrones d'EvoLink (créer → statut → résultats).
• Utiliser callback_url en toute sécurité (HTTPS uniquement, sémantique de répétition et gestion des échecs).
• Utiliser un seul point de terminaison pour le texte-en-vidéo, l'image-en-vidéo et le guidage par première et dernière image.
• Empêcher le double traitement avec des clés d'idempotence et des budgets de répétition.
• Ré-héberger les sorties avant l'expiration des liens (fenêtre de rétention de 24 heures).
• Modéliser le « coût par sortie réussie » sans s'appuyer sur des clichés de prix fragiles.
• Comparer les compromis d'intégration par rapport à Veo 3.1 et Kling O1 (basé sur la structure, pas sur le prix).

Liste de contrôle de démarrage rapide (à copier/coller dans votre ticket)

• Implémenter POST /v1/videos/generations pour créer des tâches
• Implémenter le sondage (polling) GET /v1/tasks/{task_id}
• Implémenter le point de terminaison callback_url (réponse 2xx rapide + traitement asynchrone)
• Ajouter une clé d'idempotence par intention utilisateur (clic sur « Générer »)
• Ré-héberger les actifs vidéo dans les 24 heures
• Instrumenter : latence p50/p95, taux d'échec de politique, taux de répétition, tentatives par succès

Contrat de l'API EvoLink (ce que vous implémentez réellement)

• Créer une tâche → recevoir un task_id
• Soit sonder GET /v1/tasks/{task_id}, soit recevoir un rappel sur callback_url
• À la fin, récupérer les URL des results et télécharger immédiatement (les liens expirent)

Aperçu des points de terminaison

• POST https://api.evolink.ai/v1/videos/generations

• GET https://api.evolink.ai/v1/tasks/{task_id}

• Les liens de sortie sont valides pendant 24 heures. Ré-hébergez-les rapidement.

Un point de terminaison, trois modes (détection de mode via image_urls)

• 0 image → texte-en-vidéo
• 1 image → image-en-vidéo
• 2 images → première-dernière image (guidage par la première et la dernière image)

• Max 2 images par requête
• Chaque image ≤ 10 Mo
• Formats : jpg/jpeg/png/webp
• Les URL doivent être directement accessibles par le serveur

Champs de requête importants en production

Ce sont les paramètres que vous allez réellement opérationnaliser :

• model : utilisez "seedance-1.5-pro"
• prompt (requis) : jusqu'à 2000 jetons
• duration : par défaut 5s ; supporté 4–12s

  Note opérationnelle : la facturation évolue avec la durée ; traitez la durée comme un levier budgétaire de premier plan.

• quality : 480p ou 720p (par défaut 720p)
• aspect_ratio : 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, adaptive (par défaut 16:9)
• generate_audio : booléen (par défaut true)

  Conseil : mettez le dialogue entre guillemets doubles pour améliorer la diction des lignes.

• callback_url : URL de rappel HTTPS uniquement pour les tâches terminées/échouées/annulées (recommandé)

Valeurs par défaut des paramètres par scénario (décisions rapides)

Cycle de vie des tâches : concevez d'abord votre machine d'état

Une intégration fiable commence par une machine d'état interne prévisible :

created → queued/processing → succeeded → (télécharger → ré-héberger → livré)
                     └──────→ failed (politique | transitoire | interne)
                     └──────→ cancelled

Exemples de fonctionnement minimaux (EvoLink)

1) Créer une tâche (cURL) — prêt à copier/coller

Cet exemple évite les pièges d'échappement du shell en utilisant un prompt sans guillemets simples.

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header 'Authorization: Bearer <votre_jeton>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-1.5-pro",
    "prompt": "A detective in the rain says: \"Do not move.\" Neon reflections on the street. Subtle footsteps and radio static.",
    "duration": 8,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "callback_url": "https://votre-domaine.com/webhooks/evolink-task"
  }'

L'API répond immédiatement avec un objet de tâche contenant au moins :

• id (id de la tâche)
• status
• champs usage (ex: billing_rule, credits_reserved)

2) Sonder le statut de la tâche (cURL)

curl --request GET \
  --url https://api.evolink.ai/v1/tasks/<task_id> \
  --header 'Authorization: Bearer <votre_jeton>'

Une fois terminée, la tâche comprend :

• tableau results avec les URL de sortie
• status et progress

callback_url : règles de fiabilité (ne faites pas l'impasse)

• HTTPS uniquement
• IP de réseau interne/privé bloquées
• Délai d'attente (timeout) : 10 secondes
• Max 3 répétitions avec un délai d'attente de 1 / 2 / 4 secondes
• Le corps du rappel s'aligne sur le format de réponse de la consultation de tâche

Liste de contrôle de production des rappels (copier/coller)

• Répondre 2xx en 200ms–500ms (mettre le travail en file d'attente ; ne pas faire de travail lourd en ligne)
• Valider que task_id existe et appartient à votre client/utilisateur
• Interroger immédiatement GET /v1/tasks/{task_id} avant de marquer l'état final
• Dédupliquer les rappels (stocker task_id + statut final ; ignorer les répétitions)
• Journaliser la charge utile brute du rappel pour le débogage (masquer les secrets)
• Alerter lorsque le taux d'échec des rappels augmente (indique généralement des problèmes avec votre point de terminaison)

Idempotence : empêcher le double traitement (et le double paiement)

Même si votre fournisseur est correct, votre système peut toujours créer des doublons car :

• Les utilisateurs cliquent deux fois sur « Générer »
• Les réseaux mobiles répètent la requête
• Les passerelles expirent

• Le client génère une idempotency_key par intention de l'utilisateur (un clic = une clé)
• Le serveur stocke (user_id, idempotency_key) → task_id avec un TTL
• En cas de répétition, renvoyer le même task_id au lieu de créer une nouvelle tâche

N'assumez pas que l'idempotence est « gérée pour vous » à moins que l'API ne le documente explicitement. Implémentez-la au niveau de votre application.

Livraison des actifs : le piège des 24 heures

Étant donné que les liens de sortie expirent en 24 heures, votre pipeline devrait :

• Télécharger le résultat immédiatement lorsque status=completed
• Ré-héberger dans votre stockage d'objets (S3/GCS/R2)
• Servir via un CDN
• Persister les métadonnées : task_id, hash du prompt, id utilisateur, durée, qualité, flag audio, catégorie de résultat de modération

Empêchez cela en ré-hébergeant automatiquement à la fin de la tâche.

Modélisation économique sans clichés de prix

Même si vous ne publiez jamais de chiffres de prix, vous avez toujours besoin d'un modèle économique d'unité durable.

1) Sachez sur quoi la plateforme facture

Opérationnellement, vos dépenses sont dictées par :

• duration (clip plus long → plus cher)
• generate_audio (l'audio ajoute un coût)
• Itération (les utilisateurs ont rarement raison du premier coup)

2) Budgétisez le « coût par sortie réussie », pas le « coût par tentative »

Suivez :

• attempts_per_success (par scénario)
• retry_rate
• policy_failure_rate
• p95_latency

Alors votre unité réelle :

sorties réussies par session × nombre moyen de tentatives nécessaires

3) Brouillon → Approuver → Final (réducteur de dépenses le plus fiable)

Lorsque vous voyez une itération élevée :

• Faites un brouillon en utilisant des paramètres moins chers (ex : qualité inférieure/durée plus courte)
• Finalisez avec Seedance 1.5 Pro (avec audio) seulement après approbation de l'utilisateur

Pièges de production et solutions

1) Le piège asynchrone (timeouts + jobs zombies)

• Définir un « TTL du job » et un état d'interface utilisateur « en cours de traitement »
• Suivre le temps de réalisation p95 ; dégrader gracieusement lorsqu'il pique

2) Les résultats de modération peuvent arriver en retard

Concevez des états d'interface utilisateur/backend pour les « échecs après traitement ».

• Séparer : politique vs transitoire vs interne
• Ne jamais répéter automatiquement les échecs de politique
• Fournir des conseils pour réécrire le prompt (en particulier autour du contenu sensible)

Comparaison : Seedance 1.5 Pro vs Veo 3.1 vs Kling O1

Les chiffres vieillissent vite. Comparez ce qui dure : la structure d'intégration et l'adéquation au flux de travail.

Tableau A — Forme d'intégration et de facturation

Tableau B — Matrice de décision de production

Liste de contrôle de décision (oui/non rapide)

• Vous avez besoin d'audio natif et pouvez structurer le dialogue entre guillemets.
• Vous avez besoin de texte-en-vidéo + image-en-vidéo + première/dernière image sous un seul contrat.
• Vous pouvez ré-héberger les actifs dans les 24 heures.

• Vous préférez une budgétisation basée sur la durée et un flux de travail stable dans l'écosystème Google Cloud.

• Le montage/re-style est central et vous avez confirmé une sémantique d'accès stable.

FAQ

Q : Comment basculer entre le texte-en-vidéo et l'image-en-vidéo sur EvoLink ?

Q : Webhook ou sondage — qu'est-ce qui est le plus sûr ?

Q : Pourquoi dois-je ré-héberger le résultat ?

Les liens expirent en 24 heures. Téléchargez et stockez les sorties rapidement.

Q : Comment éviter les tâches dupliquées lorsque les utilisateurs réessaient ?

Commencez à construire avec Seedance 1.5 Pro dès aujourd'hui

Vous avez vu le contrat. Vous comprenez les compromis. Maintenant, transformez-le en une fonctionnalité de production.

• Une seule clé API pour Seedance 1.5 Pro, Veo 3.1, Kling et d'autres modèles
• Tâches asynchrones + rappels avec une sémantique de répétition définie
• Facturation basée sur l'utilisation avec des crédits transparents et sans minimum

La plupart des équipes s'intègrent en moins d'une heure.