Configuration de l’API RunningHub Seedance 2.0 : clé, ressources et premier appel

AI Overview

Quelle est la méthode la plus rapide pour configurer l’API RunningHub Seedance 2.0 ?

Créez une clé API RunningHub, sélectionnez précisément l’application IA Seedance 2.0 ou la route de modèle correspondante, envoyez une requête minimale, puis interrogez régulièrement son champ taskId. N’ajoutez les téléchargements, les webhooks et les nouvelles tentatives en production qu’après la réussite de ce premier appel.

Dois-je utiliser le flux AI App API ou le flux ComfyUI ?

Utilisez le flux AI App API lorsque vous souhaitez un contrat d’entrée hébergé et figé. Utilisez la route OpenAPI ComfyUI lorsque votre équipe a besoin de cartographies de nœuds visibles, de graphes réutilisables, de préparation de ressources ou d’étapes de modèle pouvant varier d’un projet à l’autre.

Comment fonctionnent les identifiants de ressources (Seedance 2.0 asset IDs) dans RunningHub ?

Les identifiants de ressources permettent aux nœuds Seedance 2.0 compatibles de réutiliser des références préparées. L’intégration ComfyUI accepte des identifiants simples, des valeurs au format asset://, des listes séparées par des virgules ou une chaîne JSON représentant un tableau ; toutefois, le nœud choisi détermine toujours les emplacements d’entrée valides.

Pourquoi l’URL d’une tâche terminée doit-elle être copiée immédiatement ?

RunningHub génère des liens multimédias temporaires pour les téléchargements et les résultats générés. Dès qu’une tâche aboutit, transférez chaque fichier MP4 et chaque image de présentation (poster) approuvés vers votre propre stockage durable ; un identifiant de tâche conservé ne constitue pas une archive multimédia permanente.

Ce dont vous avez besoin avant votre premier appel

Une configuration fiable repose sur quatre valeurs connues : la région API, une clé valide, l’identifiant exact de l’application IA ou du modèle, et une destination de stockage sous votre contrôle. Ne copiez pas aveuglément une URL de point de terminaison issue d’un tutoriel non pertinent en supposant que son corps de requête est compatible. RunningHub expose plusieurs styles d’appel, et chaque page de documentation détaillée d’une API publiée constitue le contrat officiel de cette route. Le guide général de l’API Seedance 2.0 explique le modèle asynchrone global ; ce guide se concentre exclusivement sur RunningHub.

Gardez la clé hors du contrôle de version. Pour l’intégration officielle ComfyUI, le modèle d’environnement documenté est le suivant :

export RH_API_BASE_URL="https://www.runninghub.cn/openapi/v2"
export RH_API_KEY="replace-with-your-key"

Utilisez l’URL de base régionale indiquée dans votre propre console RunningHub et dans la documentation actuelle. Une clé client peut nécessiter un abonnement éligible, tandis que les clés d’entreprise peuvent être soumises à des règles d’accès différentes. Considérez comme deux vérifications distinctes la capacité à voir un modèle dans le catalogue et celle à l’appeler avec votre clé.

Avant de consommer des crédits, définissez un « test d’acceptation » unique : un sujet, une action, un mouvement de caméra, une durée et un ratio de livraison. Si vous doutez de la faisabilité du prompt lui-même, testez d’abord le brief créatif dans l’espace de travail du modèle Seedance 2.0. Cela permet de distinguer les problèmes liés au prompt de ceux liés à l’intégration.

Utilisez un cadre d’acceptation visuellement simple pour le premier appel. Cette image produit fraîche facilite l’inspection de la silhouette, des reflets, du mouvement de l’eau et de la stabilité de l’arrière-plan ; il ne s’agit pas d’une référence de performance officielle pour RunningHub.

Choisissez la bonne route RunningHub

RunningHub propose deux voies pratiques pour cette tâche. La route « Application IA » est utile lorsque le fournisseur a déjà intégré Seedance 2.0 dans une application stable dotée d’entrées nommées. Vous soumettez votre requête à cet identifiant d’application et recevez un champ taskId. Le plugin OpenAPI ComfyUI est préférable lorsque le graphe lui-même fait partie de votre logique de production ou lorsque vous avez besoin des assistants de ressources Seedance 2.0 qu’il fournit.

Ne mélangez pas les routes lors de votre premier test. Une requête minimale via l’application IA doit valider l’authentification, l’identifiant de l’application, la soumission à la file d’attente et la récupération du résultat. Un appel minimal via ComfyUI doit confirmer que le workflow exporté s’exécute sans modification avant d’introduire des substitutions dynamiques de nodeInfoList.

Le plugin officiel RunningHub ComfyUI peut lire sa configuration depuis un nœud de paramètres, des variables d’environnement ou un fichier .env, les paramètres du nœud ayant priorité. Notez quelle couche fournit la clé. Sinon, un collègue pourrait renouveler le secret d’environnement tandis qu’une ancienne valeur de nœud continuerait silencieusement à prévaloir.

Une prise de vue riche en références doit conserver une lisibilité claire de la personne, de la tenue, de l’animal, de la météo et du lieu. L’image est une sortie illustrative récente, non une comparaison officielle entre modèles.

Configuration étape par étape de l’API RunningHub Seedance 2.0

Commencez par un squelette de requête qui expose uniquement les variables réellement contrôlées par votre service. La documentation actuelle des applications IA RunningHub indique un point de terminaison de forme /run/ai-app/{appId} et renvoie un objet tâche comportant des états tels que QUEUED, RUNNING, SUCCESS ou FAILED. Utilisez l’exemple de requête généré sur la page de documentation détaillée de l’API comme source de vérité pour les noms des champs.

const response = await fetch(`${RUNNINGHUB_BASE}/run/ai-app/${APP_ID}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RH_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    nodeInfoList: inputMappings,
    webhookUrl: process.env.RH_WEBHOOK_URL
  })
});

if (!response.ok) throw new Error(`Échec de la soumission : ${response.status}`);
const task = await response.json();
```Pour un flux de travail ComfyUI, importez l’un des exemples correspondants, connectez uniquement `RH OpenAPI Settings` si vous n’utilisez pas de configuration d’environnement, puis exécutez le graphe avec des valeurs statiques. Une fois qu’il fonctionne, exposez uniquement les nœuds devant varier — invite (prompt), référence, durée, ratio ou options de sortie — et stockez ces identifiants de nœuds à côté de la version du flux de travail.

Les outils de ressources (Seedance 2.0) de RunningHub ajoutent une autre option. `real_person_mode=false` suit le chemin de téléchargement direct. Lorsqu’il est activé, les emplacements locaux d’images ou de vidéos sélectionnés peuvent être convertis en ressources avant la requête au modèle. `conversion_slots` contrôle quels emplacements participent. Testez d’abord une seule image, car une charge utile comportant neuf images et trois vidéos masque l’emplacement à l’origine de l’échec.

```official-video
src=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-v1.mp4
poster=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-poster-v1.jpg
label=Vidéo orbitale verticale du produit pour vérifier un résultat d’API récupéré

Cette sortie animée jouable de Seedance illustre ce qu’il faut inspecter après récupération : géométrie stable du produit, déplacement contrôlé de la caméra et image nette. Elle n’est pas présentée comme une référence de RunningHub.

Concevoir des entrées capables de traverser la frontière de l’API

L’API ne peut pas déduire quelle ressource correspond à la première image, à la dernière image, à une référence de personnage ou à une référence de style. Créez un manifeste d’entrées avant la soumission. Stockez un nom local, une somme de contrôle source, un type MIME, un emplacement cible, un identifiant de ressource (le cas échéant) et l’étiquette d’invite qui y fait référence. Cela s’avère plus utile qu’un dossier de fichiers intitulés final-2.png.

{
  "shot": "kitchen-01",
  "references": [
    {"role": "first_frame", "assetId": "asset-example-01"},
    {"role": "style", "url": "https://your-storage.example/style.jpg"}
  ],
  "prompt": "Plan moyen suivi ; le chef dresse le plat ; de la vapeur s’élève ; lumière chaude naturelle",
  "ratio": "16:9"
}

L’intégration documentée de ComfyUI accepte un seul identifiant de ressource, une valeur au format asset://<asset_ID>, des valeurs séparées par des virgules ou des retours à la ligne, ou une chaîne JSON représentant un tableau. Cette souplesse est pratique, mais la cohérence est plus sûre : choisissez une seule représentation dans votre base de code et validez-la avant l’exécution du graphe. Pour la génération vidéo à partir d’image, l’intégration identifie first_frame et last_frame ; les nœuds vidéo multimodaux peuvent exposer plusieurs emplacements d’images et de vidéos. Utilisez l’espace de travail référence-vers-vidéo pour affiner un lot de références avant son automatisation.

Rédigez les invites comme des instructions de prise exécutables. Séparez cadrage, sujet, action, environnement, éclairage et son. Si le premier appel échoue de façon créative, simplifiez un seul canal plutôt que de modifier simultanément le point de terminaison, les ressources, l’invite et le flux de travail. Le flux de travail d’invite pour la génération vidéo à partir d’image fournit un modèle d’invite réutilisable.

Ce cadre final fraîchement généré illustre un test où les mains sont lisibles, la géométrie des aliments correcte, la vapeur présente et l’éclairage naturel adapté — quatre détails à vérifier sur l’ensemble de la séquence générée.

Interroger, stocker et examiner le résultat

Après la soumission, conservez durablement l’identifiant taskId renvoyé avant d’interroger l’état. Utilisez un délai exponentiel avec plafond, arrêtez-vous en cas d’échec définitif et rendez les interrogations idempotentes afin qu’un processus redémarré puisse poursuivre la même tâche. Si votre route prend en charge un webhook, vérifiez sa signature ou son secret partagé avant de considérer la charge utile comme fiable. Le rappel (callback) doit mettre à jour l’enregistrement de tâche existant, et non créer une seconde génération.

En cas de SUCCESS, copiez immédiatement le fichier MP4. RunningHub précise que les liens vers les résultats générés et les liens de téléchargement peuvent expirer après 24 heures. Ne télécharger le fichier qu’au moment où un utilisateur humain ouvre l’écran d’analyse est donc risqué. Stockez conjointement le fichier, sa somme de contrôle, l’identifiant de tâche du fournisseur, la version de l’invite, le manifeste source et l’horodatage de génération. Ensuite, créez une vignette (poster) et un proxy compatible navigateur uniquement si votre pile de diffusion en a besoin.

Extrait animé de café et de vapeur pour examiner des mouvements subtils

Ce deuxième extrait animé réel utilise un mouvement maîtrisé des mains, de la vapeur ascendante et la lumière du soleil, offrant aux relecteurs une surface d’échec différente de celle de l’orbite du produit.

Examinez l’intégralité de la séquence, et non seulement sa première image. Évaluez l’identité, la géométrie des objets, la continuité du mouvement, la trajectoire de la caméra, la stabilité de l’arrière-plan, l’adéquation du son et la sécurité de la livraison. Une tâche techniquement réussie peut toutefois rester inutilisable. Pour les campagnes impliquant plusieurs modèles ou fournisseurs, le flux de travail vidéo IA multi-modèle montre comment préserver un même standard d’analyse sur l’ensemble des routes.

La direction du tissu, la forme des mains, le contact des pieds avec le sol, la stabilité de l’horizon et la hauteur de la caméra constituent une liste de contrôle concise pour valider un résultat fortement axé sur le mouvement.

Résoudre les erreurs courantes de l’API RunningHub Seedance 2.0

Traitez les erreurs selon leur stade dans le cycle de vie. Un code 401 ou 403 indique un problème lié à la clé, à la région, à l’appartenance ou aux autorisations — et non à l’invite. Une requête rejetée avant la génération d’un taskId signifie généralement que le point de terminaison, l’identifiant d’application, le type de contenu ou la structure du corps de la requête est incorrect. Une tâche mise en file d’attente qui ne progresse jamais révèle un problème de file d’attente ou de dépassement de délai. Une tâche marquée FAILED avec un détail de vérification du contenu nécessite une invite ou une référence plus sûre. Une tâche réussie accompagnée d’un lien expiré indique un échec de stockage.| Symptôme | Vérification initiale | Action corrective | |---|---|---| | Non autorisé | Source de la clé et région de base | Supprimez la substitution obsolète du nœud ; effectuez une rotation de la clé et testez à nouveau un appel minimal | | Mappage de nœud invalide | Version du workflow et identifiants de nœud | Exportez le graphe actuel et mettez à jour uniquement les nœuds nommés | | Échec de la conversion d’actif | Nom de l’emplacement, type et accessibilité de la source | Testez un seul emplacement ; utilisez la solution de secours par téléchargement direct documentée | | Tâche toujours en file d’attente | Intervalle d’interrogation (polling) et file d’attente du compte | Réduisez la fréquence des requêtes ; ne créez pas automatiquement de tâches en double | | URL du résultat expirée | Événement de stockage durable | Relancez uniquement si le fichier d’origine n’a jamais été copié | | Extrait visuellement incorrect | Invite (prompt) et manifeste source | Conservez l’API inchangée et modifiez une seule variable créative |

Journalisez le code d’état, le code d’erreur du fournisseur, l’identifiant de la tâche, la version du workflow et les noms de champs assainis. Ne journalisez jamais la clé API ni les URL complètes de médias privés. Ajoutez une clé d’idempotence dans votre propre service, même si la route du fournisseur ne l’expose pas ; cela empêche qu’une nouvelle tentative côté client ne déclenche deux exécutions.

Si l’intégration fonctionne techniquement mais que la coordination devient un goulot d’étranglement, utilisez Seedance Agent pour organiser les références, transformer un brief en plans, comparer les sorties approuvées et relancer uniquement l’étape ayant échoué. Il s’agit d’un choix au niveau de la production, non d’un remplacement à la compréhension de l’API sous-jacente.

Conclusion

Une configuration durable de l’API RunningHub Seedance 2.0 est un cycle de vie, pas une simple commande cURL réussie : choisissez la bonne application IA ou la bonne route ComfyUI, conservez la clé hors du code, validez un appel minimal, mappez explicitement les actifs, persistez le taskId, réduisez la fréquence des requêtes lors de l’interrogation (polling), copiez immédiatement les résultats temporaires, et évaluez l’extrait complet à l’aide d’une liste de contrôle d’acceptation écrite. Une fois ces limites stabilisées, ajoutez des webhooks, des entrées multimodales étendues, une planification par lots et une approbation humaine — sans masquer les échecs derrière une automatisation supplémentaire. Pour planifier les références et les plans avant toute dépense — et faire progresser le travail approuvé à travers les revues et les relances sélectives — démarrez le projet avec Seedance Agent.