Videogenerierung (Multi-Gateway)
Erstelle KI-Videos aus Textbeschreibungen. Unterstützt mehrere Anbieter über vier API-Pfade:
| Gateway | Umgebungsvariable | Anbieter | Tool |
|---|---|---|---|
| fal.ai | FAL_KEY | Seedance 2.0 (Standard + Schnell), 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 Offiziell | KLING_API_KEY | Kling offiziell Classic, Turbo und einfaches Omni-Video | kling_official_video |
| Gemini API | GEMINI_API_KEY / GOOGLE_API_KEY | Gemini Omni Flash (Generierung + konversationelle Bearbeitung) | gemini_omni_video |
Iterative Bearbeitung – Gemini Omni. Wenn die Aufgabe die Verfeinerung eines vorhandenen Clips (Hinzufügen/Entfernen von Objekten, Neugestaltung, Änderung der Beleuchtung oder des Bildschirmtextes) und nicht die Neuerstellung umfasst, ist Gemini Omni Flash der einzige Anbieter im Portfolio mit zustandsbehafteter Multi-Turn-Bearbeitung. Siehe Layer 3 gemini-omni für die autoritative Prompt-Anleitung (Referenzbild-Tags, Zeitcodesyntax, Bearbeitungs-Prompt-Regeln), bevor Sie einen Prompt dafür schreiben.
Bevorzugtes Premium-Standard – Seedance 2.0. Wenn ein Premium-Gateway konfiguriert ist (FAL_KEY → seedance_video oder Heygens Video Agent / Avatar Shots Pfad), ist Seedance 2.0 der bevorzugte Standard für kinoreife, Trailer- und hochauflösende Clip-Arbeiten. Es ist das einzige Modell im Portfolio mit nativem Single-Pass-Synchron-Audio, Multi-Shot-Generierung, Director-Level-Kamerasteuerung und Lippen-Synchronisation aus zitiertem Dialog, und es belegt Platz 1 auf dem Artificial Analysis Elo Stand Anfang 2026. Weichen Sie nur davon ab, wenn der Nutzer einen bestimmten Grund hat (Budget, Anbieterpräferenz, stilistische Eignung wie VEO für fotorealistische Landschaften oder Kling für einen bestimmten Anime-Look). Siehe Layer 3 seedance-2-0 für die autoritative Prompt- und Parameter-Anleitung.
WICHTIG: Verwenden Sie immer video_selector anstatt die Anbieter-Tools direkt aufzurufen. Der Selektor übernimmt Verfügbarkeitsprüfungen, Kostenvergleiche und automatische Fallbacks, und seine Bewertungs-Engine bevorzugt bereits Seedance 2.0 für kinoreife Absichten.
Authentifizierung
Verwenden Sie das Gateway, das am besten zu den verfügbaren Anbietern und Kosten/Qualitätszielen des Nutzers passt.
- HeyGen: Setzen Sie
HEYGEN_API_KEY, um Zugriff auf das Multi-Modell-Gateway zu erhalten. - fal.ai: Setzen Sie
FAL_KEY, um über fal.ai auf Kling, MiniMax und Veo zuzugreifen. - Kling Offiziell: Setzen Sie
KLING_API_KEY, um auf die offizielle direkte Kling-API überprovider="kling_official"zuzugreifen. - Gemini API: Setzen Sie
GEMINI_API_KEYoderGOOGLE_API_KEY, um auf die Gemini-Omni-Videogenerierung und konversationelle Bearbeitung zuzugreifen.
Beschreiben Sie kein Gateway als Standard oder erste Wahl, ohne zuvor das Registry und die aktuelle Aufgabenpassung zu überprüfen.
fal.ai Kling (kling_video, provider="kling") und Kling Offiziell (kling_official_video, provider="kling_official") sind unterschiedliche Pfade. Verwenden Sie keine fal.ai-Warteschlangen-URLs, FAL_KEY oder Bild-Upload-Verhalten wieder, wenn der offizielle Anbieter ausgewählt ist.
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": "Eine Drohnenaufnahme über einer Küstenstadt bei Sonnenuntergang"}}'
Standard-Workflow
- Rufen Sie
POST /v1/workflows/executionsmitworkflow_type: "GenerateVideoNode"und Ihrem Prompt auf - Sie erhalten eine
execution_idin der Antwort - Pollen Sie
GET /v1/workflows/executions/{id}alle 10 Sekunden, bis der Statuscompletedist - Verwenden Sie die zurückgegebene
video_urlaus der Ausgabe
Videogenerierung ausführen
Endpunkt
POST https://api.heygen.com/v1/workflows/executions
Anfragefelder
| Feld | Typ | Erf | Beschreibung |
|---|---|---|---|
workflow_type | string | J | Muss "GenerateVideoNode" sein |
input.prompt | string | J | Textbeschreibung des zu generierenden Videos |
input.provider | string | Videogenerierungs-Anbieter (Standard: "veo_3_1"). Siehe Anbieter unten. | |
input.aspect_ratio | string | Seitenverhältnis (Standard: "16:9"). Übliche Werte: "16:9", "9:16", "1:1" | |
input.reference_image_url | string | Referenzbild-URL für Bild-zu-Video-Generierung | |
input.tail_image_url | string | Endbild-URL für die Letztbild-Steuerung | |
input.config | object | Anbieterspezifische Konfigurationsüberschreibungen |
Anbieter
| Anbieter | Wert | Beschreibung |
|---|---|---|
| VEO 3.1 | "veo_3_1" | Google VEO 3.1 (Standard, höchste Qualität) |
| VEO 3.1 Schnell | "veo_3_1_fast" | Schnellere VEO 3.1 Variante |
| VEO 3 | "veo3" | Google VEO 3 |
| VEO 3 Schnell | "veo3_fast" | Schnellere VEO 3 Variante |
| VEO 2 | "veo2" | Google VEO 2 |
| Kling Pro | "kling_pro" | Kling Pro Modell |
| Kling V2 | "kling_v2" | Kling V2 Modell |
| 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 Destilliert | "ltx_distilled" | LTX Destilliert (schnellste) |
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": "Eine Drohnenaufnahme über einer Küstenstadt zur goldenen Stunde, kinoreife Beleuchtung",
"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"]
Antwortformat
{
"data": {
"execution_id": "node-gw-v1d2e3o4",
"status": "submitted"
}
}
Status prüfen
Endpunkt
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"
Antwortformat (Abgeschlossen)
{
"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"
}
}
}
Polling auf Abschluss
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(`Videogenerierung übermittelt: ${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 || "Videogenerierung fehlgeschlagen");
case "not_found":
throw new Error("Workflow nicht gefunden");
default:
await new Promise((r) => setTimeout(r, pollIntervalMs));
}
}
throw new Error("Videogenerierung Zeitüberschreitung");
}
Nutzungsbeispiele
Einfaches Text-zu-Video
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": "Eine Person, die durch einen sonnenbeschienenen Park geht, flache Tiefenschärfe"
}
}'
Bild-zu-Video
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Animieren Sie dieses Produktfoto mit einem langsamen Zoom und sanften Partikeleffekten",
"reference_image_url": "https://example.com/product-photo.png",
"provider": "kling_pro"
}
}
Vertikales Format für soziale Medien
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Ein trendiges Café-Interieur, die Kamera schwenkt langsam über die Theke",
"aspect_ratio": "9:16",
"provider": "veo_3_1"
}
}
Schnelle Generierung mit LTX
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Abstrakte bunte Formen, die sich verwandeln und fließen",
"provider": "ltx_distilled"
}
}
Best Practices
- Seien Sie beschreibend in Prompts – geben Sie Kamerabewegung, Beleuchtung, Stil und Stimmung im Detail an
- Standardmäßig Seedance 2.0 (via
seedance_video) für kinoreife und bewegungsgeführte Arbeiten verwenden wennFAL_KEYgesetzt ist – Single-Pass-Synchron-Audio, Multi-Shot, Lippen-Synchronisation, Director-Level-Kamera. Verwenden Sie VEO 3.1 / Sora V2 Pro, wenn der Nutzer speziell Google- oder OpenAI-Bewegungscharakter wünscht; verwenden Sieltx_distilledoderveo3_fastnur, wenn Geschwindigkeit die harte Einschränkung ist - Referenzbilder verwenden für Bild-zu-Video-Generierung – ideal zum Animieren von Produktfotos oder Standbildern
- Videogenerierung ist der langsamste Workflow – erlauben Sie bis zu 5 Minuten, pollt alle 10 Sekunden
- Seitenverhältnis ist wichtig – verwenden Sie
9:16für soziale Medien Stories/Reels,16:9für Landschaft,1:1für quadratisch - Ausgabe enthält
asset_id– verwenden Sie diese, um auf das generierte Video in anderen HeyGen-Workflows zu verweisen - Ausgabe-URLs sind temporär – laden Sie generierte Videos umgehend herunter oder speichern Sie sie