Videogenerierung (Multi-Gateway)
Erzeuge KI-Videos aus Textaufforderungen. Unterstützt mehrere Anbieter über zwei API-Gateways:
| Gateway | Umgebungsvariable | Anbieter | Tool |
|---|---|---|---|
| fal.ai | FAL_KEY | Seedance 2.0 (Standard + Fast), 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 |
Bevorzugter Premium-Standard – Seedance 2.0. Wenn ein Premium-Gateway konfiguriert ist (FAL_KEY → seedance_video oder der HeyGen Video Agent / Avatar Shots Pfad) ist Seedance 2.0 die bevorzugte Standardeinstellung für filmische, Trailer- und hochauflösende Clip-Arbeiten. Es ist das einzige Modell im Angebot mit nativem synchronisiertem Audio in einem Durchlauf, Multi-Shot-Generierung, Kamerasteuerung auf Regie-Niveau und Lippen-Synchronisation aus zitiertem Dialog, und es belegt Platz 1 im Artificial Analysis Elo Stand Anfang 2026. Wechsle nur dann von diesem Modell ab, wenn der Benutzer einen spezifischen 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 maßgebliche Anleitung zu Eingabeaufforderungen und Parametern.
WICHTIG: Verwende immer video_selector anstatt Anbieter-Tools direkt aufzurufen. Der Selektor übernimmt Verfügbarkeitsprüfungen, Kostenvergleiche und automatische Fallbacks, und seine Bewertungslogik priorisiert bereits Seedance 2.0 für filmische Absichten.
Authentifizierung
Verwende das Gateway, das am besten zu den verfügbaren Anbietern und den Kosten-/Qualitätszielen des Benutzers passt.
- HeyGen: Setze
HEYGEN_API_KEYum Zugriff auf das Multi-Modell-Gateway zu erhalten. - fal.ai: Setze
FAL_KEYum Zugriff auf Kling, MiniMax und Veo über fal.ai zu erhalten.
Beschreibe keines der Gateways als Standard oder beste Wahl, ohne zuvor die Registry und die aktuelle Aufgabenpassung zu prüfen.
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
- Rufe
POST /v1/workflows/executionsmitworkflow_type: "GenerateVideoNode"und deiner Eingabeaufforderung auf - Erhalte eine
execution_idin der Antwort - Frage
GET /v1/workflows/executions/{id}alle 10 Sekunden ab, bis der Statuscompletedlautet - Verwende 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 | Anbieter für Videogenerierung (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 Führung des letzten Frames | |
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 Fast | "veo_3_1_fast" | Schnellere VEO 3.1 Variante |
| VEO 3 | "veo3" | Google VEO 3 |
| VEO 3 Fast | "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 Distilled | "ltx_distilled" | LTX Distilled (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, filmische 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 eingereicht: ${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 abgelaufen");
}
Verwendungsbeispiele
Einfache 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 sonnigen Park geht, geringe Schärfentiefe"
}
}'
Bild-zu-Video
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Animieren Sie dieses Produktfoto mit einem langsamen Zoom und weichen Partikeleffekten",
"reference_image_url": "https://example.com/product-photo.png",
"provider": "kling_pro"
}
}
Hochformat für soziale Medien
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Ein trendiges Café-Interieur, die Kamera schwenkt langsam über den Tresen",
"aspect_ratio": "9:16",
"provider": "veo_3_1"
}
}
Schnelle Generierung mit LTX
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Abstrakte bunte Formen, die sich verändern und fließen",
"provider": "ltx_distilled"
}
}
Best Practices
- Sei beschreibend in der Eingabeaufforderung – gib Details zu Kamerabewegung, Beleuchtung, Stil und Stimmung an
- Standardmäßig Seedance 2.0 (über
seedance_video) für filmische und bewegungsorientierte Arbeiten wennFAL_KEYgesetzt ist – synchronisierter Audio in einem Durchlauf, Multi-Shot, Lippen-Synchronisation, Kamerasteuerung auf Regie-Niveau. Verwende VEO 3.1 / Sora V2 Pro nur, wenn der Benutzer speziell Google- oder OpenAI-Bewegungscharakter wünscht; verwendeltx_distilledoderveo3_fastnur, wenn Geschwindigkeit die harte Einschränkung ist - Verwende Referenzbilder für Bild-zu-Video-Generierung – großartig, um Produktfotos oder Standbilder zu animieren
- Videogenerierung ist der langsamste Workflow – erlaube bis zu 5 Minuten, frage alle 10 Sekunden ab
- Seitenverhältnis ist wichtig – verwende
9:16für Social-Media-Stories/Reels,16:9für Querformat,1:1für Quadrat - Die Ausgabe enthält eine
asset_id– verwende diese, um auf das generierte Video in anderen HeyGen-Workflows zu verweisen - Ausgabe-URLs sind temporär – lade generierte Videos umgehend herunter oder speichere sie