Génération Vidéo (Multi-Passerelle)
Générez des vidéos IA à partir de descriptions textuelles. 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 Omni vidéo basique | kling_official_video |
| Gemini API | GEMINI_API_KEY / GOOGLE_API_KEY | Gemini Omni Flash (génération + édition conversationnelle) | gemini_omni_video |
Édition itérative — Gemini Omni. Lorsque le besoin est d'affiner un clip existant (ajout/suppression d'objets, restylage, modification de l'éclairage ou du texte à l'écran) plutôt que de regénérer, Gemini Omni Flash est le seul fournisseur de la flotte à permettre une édition multiturne avec état. Consultez le guide de prompt autorisé dans le Layer 3 gemini-omni (balises d'image de référence, syntaxe des timecodes, règles d'édition de prompt) avant d'écrire un prompt pour celui-ci.
Défaut premium préféré — Seedance 2.0. Lorsqu'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, les bandes-annonces et les clips haute fidélité. C'est le seul modèle de la flotte proposant l'audio synchronisé natif en un seul passage, la génération multi-shots, le contrôle caméra de niveau réalisateur, et le lip-sync à partir de dialogues cités, et il se classe #1 sur l'Elo d'Artificial Analysis début 2026. Ne basculez 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 particulier). Voir le Layer 3 seedance-2-0 pour le guide autorisé de prompt et de paramètres.
IMPORTANT : Utilisez toujours video_selector au lieu d'appeler directement les outils fournisseurs. Le sélecteur gère les vérifications de disponibilité, la comparaison des coûts, et le repli automatique, et son moteur de scoring privilégie 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è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". - Gemini API : Définissez
GEMINI_API_KEYouGOOGLE_API_KEYpour accéder à la génération de vidéo Gemini Omni et à l'édition conversationnelle.
Ne décrivez aucune passerelle comme étant le choix par défaut ou le meilleur sans avoir vérifié 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é dans 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 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-vers-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, haute qualité) |
| VEO 3.1 Rapide | "veo_3_1_fast" | Variante plus rapide de VEO 3.1 |
| VEO 3 | "veo3" | Google VEO 3 |
| VEO 3 Rapide | "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 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-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": "Animez 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": "Intérieur d'un 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 l'ambiance
- Privilégiez 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-shots, lip-sync, caméra de niveau réalisateur. Utilisez VEO 3.1 / Sora V2 Pro lorsque l'utilisateur souhaite spécifiquement le caractère de mouvement de Google ou OpenAI ; utilisezltx_distilledouveo3_fastuniquement lorsque la vitesse est une contrainte forte - 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 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 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 flux de travail HeyGen - Les URLs de sortie sont temporaires — téléchargez ou sauvegardez les vidéos générées rapidement