runapi-ai/heygen-video

HeyGen Video sur RunAPI

Choisir la voie

• Pour un artefact ou résultat ponctuel, utilisez le service enregistré heygen-video dans la CLI runapi. Si le catalogue de commandes installé ne le liste pas, arrêtez-vous et signalez le service manquant sans inventer de commande.
• Pour une application, un backend, un worker, une bibliothèque, un pipeline webhook ou une base de code de production, rendez-vous directement sur Intégrer avec SDK. N'utilisez jamais la CLI comme runtime de production.

Découvrir le contrat

Authentifiez-vous, puis inspectez le catalogue de commandes installé et le contrat actuel de l'opération sélectionnée :

runapi auth status > auth.json
jq -e '.authenticated == true' auth.json
runapi heygen-video --help
runapi heygen-video <operation> --help
curl --fail --location https://runapi.ai/docs/api/heygen-video/<operation>.md --output contract.md

Si l'authentification est fausse, arrêtez-vous avant de soumettre. Demandez à l'utilisateur de fournir une RUNAPI_API_KEY valide, ou importez une clé fournie par l'utilisateur depuis stdin avec runapi auth import-token --token - ; utilisez la connexion interactive du navigateur uniquement lorsque l'utilisateur le demande explicitement. Choisissez <operation> uniquement parmi l'aide du service. Considérez l'aide de la commande comme faisant autorité pour l'opération installée, le modèle et la liste des champs de premier niveau. Considérez sa référence API comme faisant autorité pour le schéma complet de la requête, les champs imbriqués, les règles conditionnelles, le comportement des tâches et les variantes de réponse. Si les deux surfaces sont en désaccord, arrêtez-vous et signalez l'incohérence du contrat sans deviner.

Construire la requête

Créez request.json en JSON valide en utilisant uniquement les champs acceptés par le contrat de l'opération découverte. Pour le modèle et les valeurs choisis, évaluez chaque règle conditionnelle applicable comme un ensemble : satisfaites chaque champ obligatoire, omettez chaque champ interdit, et arrêtez-vous en cas de contradictions non résolues.

Parcourez les objets et tableaux imbriqués avant l'exécution. Fermez chaque relation énoncée par le contrat découvert, y compris les contraintes d'unicité et les références croisées entre valeurs imbriquées.

Pour une entrée média locale découverte, y compris les champs de type fichier et les champs d'URL média de premier niveau, mettez un chemin de fichier local lisible par l'agent directement dans request.json. La CLI consomme les champs de fichier tels que déclarés et télécharge les chemins locaux dans les champs d'URL média de premier niveau. Utilisez runapi files create uniquement lorsque l'utilisateur a besoin d'une URL réutilisable, fournit du Base64, ou que le contrat découvert exige explicitement un téléchargement séparé.

Validez le fichier avant de l'envoyer :

jq empty request.json

Exécuter

Soumettez exactement une fois et persistez la réponse de la tâche avant d'attendre :

runapi heygen-video <operation> --async --input-file request.json > task.json
task_id="$(jq -er '.id' task.json)"

Pour un résultat ponctuel, attendez immédiatement cette même tâche et enregistrez la réponse JSON complète. Cette attente bloquante est le comportement par défaut :

runapi wait "$task_id" --service heygen-video --action <operation> > result.json

Uniquement lorsque l'utilisateur demande explicitement une exécution en arrière-plan, une interrogation ou une intégration webhook, vous pouvez vous arrêter après avoir validé task.json. Signalez l'ID de la tâche et n'affirmez pas que le livrable est complet.

Vérifier

Un statut de succès n'est pas le livrable. Lisez et validez la réponse complète conformément au contrat de résultat découvert. Conservez le résultat non-média complet dans le format exact demandé, y compris JSON, texte, SRT ou VTT.

Pour chaque livrable média demandé listé dans la réponse, téléchargez-les tous plutôt que de ne retourner que la première URL. Avant de télécharger, déduisez son type MIME ou sa famille attendue à partir des métadonnées de réponse lorsqu'elles sont présentes, puis du format de sortie sélectionné, puis d'un champ de résultat sans ambiguïté tel que videos, images ou audios dans la référence API. Les familles de repli déclarées par le catalogue pour cette compétence sont video/*. Arrêtez-vous uniquement lorsqu'aucun type ou famille attendu unique ne peut être établi à partir de ces sources.

Pour chaque fichier téléchargé, exigez à la fois un fichier non vide et le type MIME ou la famille attendu(e) :

curl --fail --location <deliverable-url> --output <downloaded-file>
for file in <downloaded-files>; do
  expected_mime=<expected-MIME-or-family-pattern-for-this-file>
  test -s "$file"
  [[ "$(file --brief --mime-type "$file")" == $expected_mime ]]
done

Ne signalez pas la complétion lorsqu'un livrable demandé est manquant, vide ou a un type MIME inattendu. Enregistrez la Conformité de la compétence séparément du Résultat de la tâche afin qu'un échec du service ne cache pas si cette recette a été suivie.

Récupérer ou s'arrêter

• Corrigez la forme d'une requête au maximum une fois, et seulement lorsque le contrat découvert ou l'erreur de validation retournée identifie la correction.
• Réessayez une panne de transport transitoire au maximum une fois, et seulement lorsque des preuves confirment qu'aucune tâche n'a été créée, qu'aucune facturation n'a eu lieu et que réessayer est sûr.
• Si l'attente expire ou perd le transport après l'existence de task.json, conservez l'erreur et relancez runapi wait pour cette même tâche au maximum une fois. Ne soumettez jamais une tâche de remplacement.
• En cas d'échec terminal de RunAPI ou du service, conservez la preuve de la tâche/de l'erreur et arrêtez-vous. Conservez le modèle et la capacité sélectionnés, et ne soumettez pas une autre requête payante sans autorisation de l'utilisateur.
• Si le contrat manque d'un fait nécessaire pour construire ou vérifier la requête, arrêtez-vous et signalez le manque du contrat. Ne transformez pas un défaut de produit en contournement permanent de la compétence.

Intégrer avec SDK

Utilisez cette voie uniquement pour une intégration applicative ou de code de production. Ouvrez la référence SDK RunAPI actuelle ci-dessous, sélectionnez le package pour le langage cible et HeyGen Video, et confirmez sa commande d'installation, ses méthodes client, ses types de requête, ses types de réponse et ses classes d'erreur avant de coder. Construisez la requête à partir du même contrat de produit découvert et appliquez les mêmes règles de vérification des livrables et d'arrêt. N'invoquez pas runapi en tant que sous-processus à partir de code de production.

Références

• Aperçu du modèle, tarifs et limites de débit : https://runapi.ai/models/heygen-video.md
• Aperçu du fournisseur : https://runapi.ai/providers/heygen.md
• Catalogue complet des modèles : https://runapi.ai/models.md
• Intégration SDK : https://github.com/runapi-ai/heygen-video-sdk