Génération Vidéo (Multi-Passerelle)
Générer des vidéos IA à partir de descriptions textuelles. Prend en charge plusieurs fournisseurs via deux passerelles API :
| Passerelle | Variable d'environnement | Fournisseurs | Outil |
|---|---|---|---|
| fal.ai | FAL_KEY | Seedance 2.0 (standard + rapide), Kling v3/v2.1, MiniMax, VEO | seedance_video, kling_video, minimax_video, veo_video |
| HeyGen | HEYGEN_API_KEY | VEO 3.1, Kling Pro, Sora v2, Runway Gen-4, Seedance Pro / Lite (1.x) | heygen_video |
Valeur par défaut premium préférée — Seedance 2.0. Si une passerelle premium est configurée (FAL_KEY → seedance_video ou le chemin Video Agent / Avatar Shots de HeyGen), Seedance 2.0 est le choix par défaut pour les travaux cinématiques, bandes-annonces et clips haute fidélité. C'est le seul modèle de la flotte qui offre un son natif synchronisé en un seul passage, une génération multi-plans, un contrôle caméra au niveau réalisateur et un lip-sync à partir de dialogues, et il se classe #1 sur l'Elo d'Artificial Analysis début 2026. Ne l'utilisez que si l'utilisateur a une raison spécifique (budget, préférence de fournisseur, adéquation stylistique comme VEO pour les paysages photoréalistes ou Kling pour un look anime spécifique). Voir Layer 3 seedance-2-0 pour le guide de prompt et de paramètres.
IMPORTANT : Utilisez toujours video_selector au lieu d'appeler directement les outils des fournisseurs. Le sélecteur gère la vérification de disponibilité, la comparaison des coûts et le basculement automatique, et son moteur de scoring favorise déjà Seedance 2.0 pour les intentions cinématiques.
Authentification
Utilisez la passerelle configurée qui correspond le mieux aux fournisseurs disponibles de l'utilisateur et à ses objectifs de coût/qualité.
- HeyGen : Définissez
HEYGEN_API_KEYpour accéder à la passerelle multi-modèles. - fal.ai : Définissez
FAL_KEYpour accéder à Kling, MiniMax et Veo via fal.ai.
Ne décrivez aucune passerelle comme étant par défaut ou meilleure sans vérifier d'abord le registre et l'adéquation de la tâche en cours.
curl -X POST "https://api.heygen.com/v1/workflows/executions" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workflow_type": "GenerateVideoNode", "input": {"prompt": "Un plan de drone survolant une ville côtière au coucher du soleil"}}'
Workflow par défaut
- Appelez
POST /v1/workflows/executionsavecworkflow_type: "GenerateVideoNode"et votre prompt - Recevez un
execution_iddans la réponse - Interrogez
GET /v1/workflows/executions/{id}toutes les 10 secondes jusqu'à ce que le statut soitcompleted - Utilisez le
video_urlrenvoyé depuis la sortie
Exécuter la génération vidéo
Point de terminaison
POST https://api.heygen.com/v1/workflows/executions
Champs de la requête
| Champ | Type | Oblig | Description |
|---|---|---|---|
workflow_type | string | O | Doit être "GenerateVideoNode" |
input.prompt | string | O | Description textuelle de la vidéo à générer |
input.provider | string | Fournisseur de génération vidéo (par défaut : "veo_3_1"). Voir les fournisseurs ci-dessous. | |
input.aspect_ratio | string | Ratio d'aspect (par défaut : "16:9"). Valeurs courantes : "16:9", "9:16", "1:1" | |
input.reference_image_url | string | URL d'une image de référence pour la génération image-vers-vidéo | |
input.tail_image_url | string | URL d'une image de fin pour guider la dernière image | |
input.config | object | Surcharges de configuration spécifiques au fournisseur |
Fournisseurs
| Fournisseur | Valeur | Description |
|---|---|---|
| VEO 3.1 | "veo_3_1" | Google VEO 3.1 (par défaut, meilleure qualité) |
| VEO 3.1 Fast | "veo_3_1_fast" | Variante plus rapide de VEO 3.1 |
| VEO 3 | "veo3" | Google VEO 3 |
| VEO 3 Fast | "veo3_fast" | Variante plus rapide de VEO 3 |
| VEO 2 | "veo2" | Google VEO 2 |
| Kling Pro | "kling_pro" | Modèle Kling Pro |
| Kling V2 | "kling_v2" | Modèle Kling V2 |
| Sora V2 | "sora_v2" | OpenAI Sora V2 |
| Sora V2 Pro | "sora_v2_pro" | OpenAI Sora V2 Pro |
| Runway Gen-4 | "runway_gen4" | Runway Gen-4 |
| Seedance Lite | "seedance_lite" | Seedance Lite |
| Seedance Pro | "seedance_pro" | Seedance Pro |
| LTX Distilled | "ltx_distilled" | LTX Distilled (le plus rapide) |
curl
curl -X POST "https://api.heygen.com/v1/workflows/executions" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Un plan de drone survolant une ville côtière à l'heure dorée, éclairage cinématographique",
"provider": "veo_3_1",
"aspect_ratio": "16:9"
}
}'
TypeScript
interface GenerateVideoInput {
prompt: string;
provider?: string;
aspect_ratio?: string;
reference_image_url?: string;
tail_image_url?: string;
config?: Record<string, any>;
}
interface ExecuteResponse {
data: {
execution_id: string;
status: "submitted";
};
}
async function generateVideo(input: GenerateVideoInput): Promise<string> {
const response = await fetch("https://api.heygen.com/v1/workflows/executions", {
method: "POST",
headers: {
"X-Api-Key": process.env.HEYGEN_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({
workflow_type: "GenerateVideoNode",
input,
}),
});
const json: ExecuteResponse = await response.json();
return json.data.execution_id;
}
Python
import requests
import os
def generate_video(
prompt: str,
provider: str = "veo_3_1",
aspect_ratio: str = "16:9",
reference_image_url: str | None = None,
tail_image_url: str | None = None,
) -> str:
payload = {
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": prompt,
"provider": provider,
"aspect_ratio": aspect_ratio,
},
}
if reference_image_url:
payload["input"]["reference_image_url"] = reference_image_url
if tail_image_url:
payload["input"]["tail_image_url"] = tail_image_url
response = requests.post(
"https://api.heygen.com/v1/workflows/executions",
headers={
"X-Api-Key": os.environ["HEYGEN_API_KEY"],
"Content-Type": "application/json",
},
json=payload,
)
data = response.json()
return data["data"]["execution_id"]
Format de réponse
{
"data": {
"execution_id": "node-gw-v1d2e3o4",
"status": "submitted"
}
}
Vérifier le statut
Point de terminaison
GET https://api.heygen.com/v1/workflows/executions/{execution_id}
curl
curl -X GET "https://api.heygen.com/v1/workflows/executions/node-gw-v1d2e3o4" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Format de réponse (Terminé)
{
"data": {
"execution_id": "node-gw-v1d2e3o4",
"status": "completed",
"output": {
"video": {
"video_url": "https://resource.heygen.ai/generated/video.mp4",
"video_id": "abc123"
},
"asset_id": "asset-xyz789"
}
}
}
Sondage pour la complétion
async function generateVideoAndWait(
input: GenerateVideoInput,
maxWaitMs = 600000,
pollIntervalMs = 10000
): Promise<{ video_url: string; video_id: string; asset_id: string }> {
const executionId = await generateVideo(input);
console.log(`Génération vidéo soumise : ${executionId}`);
const startTime = Date.now();
while (Date.now() - startTime < maxWaitMs) {
const response = await fetch(
`https://api.heygen.com/v1/workflows/executions/${executionId}`,
{ headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
);
const { data } = await response.json();
switch (data.status) {
case "completed":
return {
video_url: data.output.video.video_url,
video_id: data.output.video.video_id,
asset_id: data.output.asset_id,
};
case "failed":
throw new Error(data.error?.message || "La génération vidéo a échoué");
case "not_found":
throw new Error("Workflow introuvable");
default:
await new Promise((r) => setTimeout(r, pollIntervalMs));
}
}
throw new Error("La génération vidéo a expiré");
}
Exemples d'utilisation
Texte-vers-vidéo simple
curl -X POST "https://api.heygen.com/v1/workflows/executions" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Une personne marchant dans un parc ensoleillé, faible profondeur de champ"
}
}'
Image-vers-vidéo
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Animer cette photo de produit avec un zoom lent et des effets de particules doux",
"reference_image_url": "https://example.com/product-photo.png",
"provider": "kling_pro"
}
}
Format vertical pour réseaux sociaux
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Intérieur d'un café tendance, la caméra panoramique lentement sur le comptoir",
"aspect_ratio": "9:16",
"provider": "veo_3_1"
}
}
Génération rapide avec LTX
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Formes colorées abstraites qui se transforment et coulent",
"provider": "ltx_distilled"
}
}
Bonnes pratiques
- Soyez descriptif dans les prompts — incluez les détails de mouvement de caméra, éclairage, style et ambiance
- Par défaut, utilisez Seedance 2.0 (via
seedance_video) pour les travaux cinématiques et axés sur le mouvement lorsqueFAL_KEYest défini — son synchronisé en un seul passage, multi-plans, lip-sync, contrôle caméra au niveau réalisateur. Utilisez VEO 3.1 / Sora V2 Pro lorsque l'utilisateur souhaite spécifiquement le mouvement des personnages de Google ou OpenAI ; utilisezltx_distilledouveo3_fastuniquement lorsque la vitesse est une contrainte stricte - Utilisez des images de référence pour la génération image-vers-vidéo — idéal pour animer des photos de produits ou des images fixes
- La génération vidéo est le workflow le plus lent — prévoyez jusqu'à 5 minutes, interrogez toutes les 10 secondes
- Le ratio d'aspect est important — utilisez
9:16pour les stories/reels sur les réseaux sociaux,16:9pour le paysage,1:1pour le carré - La sortie inclut
asset_id— utilisez-le pour référencer la vidéo générée dans d'autres workflows HeyGen - Les URLs de sortie sont temporaires — téléchargez ou sauvegardez les vidéos générées rapidement