Génération Vidéo (Multi-Passerelle)
Générez des vidéos IA à partir de prompts textuels. Prend en charge plusieurs fournisseurs via quatre chemins d'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 |
| Kling Officiel | KLING_API_KEY | Kling officiel Classic, Turbo, et vidéo Omni de base | kling_official_video |
| API Gemini | GEMINI_API_KEY / GOOGLE_API_KEY | Gemini Omni Flash (génération + édition conversationnelle) | gemini_omni_video |
Édition itérative — Gemini Omni. Lorsque le brief demande d'affiner un clip existant (ajouter/supprimer des objets, restyler, changer l'éclairage ou le texte à l'écran) plutôt que de le régénérer, Gemini Omni Flash est le seul fournisseur de la flotte avec une édition multi-tours stateful. Voir le Calque 3 gemini-omni pour le guide de prompting officiel (balises d'image de référence, syntaxe de timecode, règles de prompt d'édition) avant d'écrire un prompt.
Par défaut premium préféré — Seedance 2.0. Lorsqu'une passerelle premium est configurée (FAL_KEY → seedance_video, ou le chemin Agent Vidéo / Avatars Shots de HeyGen), Seedance 2.0 est le choix par défaut préféré pour les travaux cinématiques, de bande-annonce et de clips haute-fidélité. C'est le seul modèle de la flotte avec un audio natif synchronisé en un seul passage, une génération multi-plans, un contrôle caméra de niveau réalisateur et un lip-sync à partir de dialogues cités, et il est classé #1 sur l'Elo d'Artificial Analysis début 2026. Ne l'utilisez pas seulement lorsque 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 le Calque 3 seedance-2-0 pour le guide de prompting et de paramètres officiel.
IMPORTANT : Utilisez toujours video_selector au lieu d'appeler directement les outils des fournisseurs. Le sélecteur gère les vérifications de disponibilité, la comparaison des coûts et le repli automatique, et son moteur de notation favorise déjà Seedance 2.0 pour les intentions cinématiques.
Authentification
Utilisez la passerelle configurée qui correspond le mieux aux fournisseurs disponibles et aux objectifs de coût/qualité de l'utilisateur.
- HeyGen : Définissez
HEYGEN_API_KEYpour accéder à la passerelle multi-modèle. - fal.ai : Définissez
FAL_KEYpour accéder à Kling, MiniMax et Veo via fal.ai. - Kling Officiel : Définissez
KLING_API_KEYpour accéder à l'API directe officielle de Kling viaprovider="kling_official". - API Gemini : Définissez
GEMINI_API_KEYouGOOGLE_API_KEYpour accéder à la génération vidéo Gemini Omni et à l'édition conversationnelle.
Ne décrivez aucune passerelle comme étant la passerelle par défaut ou le meilleur choix sans d'abord vérifier le registre et l'adéquation de la tâche actuelle.
fal.ai Kling (kling_video, provider="kling") et Kling Officiel (kling_official_video, provider="kling_official") sont des chemins différents. Ne réutilisez pas les URLs de file d'attente fal.ai, FAL_KEY ou le comportement de téléchargement d'image lorsque le fournisseur officiel est sélectionné.
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"}}'
Flux de Travail 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_urlretourné depuis la sortie
Exécuter la Génération Vidéo
Point d'Accès
POST https://api.heygen.com/v1/workflows/executions
Champs de la Requête
| Champ | Type | Req | 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 de l'image de référence pour la génération image-à-vidéo | |
input.tail_image_url | string | URL de l'image de fin pour le guidage de 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 Rapide | "veo_3_1_fast" | Variante VEO 3.1 plus rapide |
| VEO 3 | "veo3" | Google VEO 3 |
| VEO 3 Rapide | "veo3_fast" | Variante VEO 3 plus rapide |
| 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 Distillé | "ltx_distilled" | LTX Distillé (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 d'Accès
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"
}
}
}
Interrogation pour l'Achèvement
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("Flux de travail non trouvé");
default:
await new Promise((r) => setTimeout(r, pollIntervalMs));
}
}
throw new Error("La génération vidéo a expiré");
}
Exemples d'Utilisation
Texte-à-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-à-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 les Réseaux Sociaux
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Un intérieur de café branché, caméra panoramique lente 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 mouvements de caméra, l'éclairage, le style et les détails d'ambiance
- Par défaut, choisissez Seedance 2.0 (via
seedance_video) pour les travaux cinématiques et axés sur le mouvement lorsqueFAL_KEYest défini — audio synchronisé en un seul passage, multi-plans, lip-sync, caméra de niveau réalisateur. Utilisez VEO 3.1 / Sora V2 Pro lorsque l'utilisateur souhaite spécifiquement le personnage en mouvement de Google ou OpenAI ; utilisezltx_distilledouveo3_fastuniquement lorsque la vitesse est la contrainte forte. - Utilisez des images de référence pour la génération image-à-vidéo — idéal pour animer des photos de produits ou des images fixes.
- La génération vidéo est le flux de travail 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 des réseaux sociaux,16:9pour le paysage,1:1pour le carré. - La sortie inclut
asset_id— utilisez-la pour référencer la vidéo générée dans d'autres flux de travail HeyGen. - Les URLs de sortie sont temporaires — téléchargez ou sauvegardez les vidéos générées rapidement.