Videogenerierung (Multi-Gateway)
Generieren Sie KI-Videos aus Text-Prompts. 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 Official | KLING_API_KEY | Kling Official Classic, Turbo und Basic 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 von Beleuchtung oder Bildschirmtext) und nicht die Neugenerierung erfordert, ist Gemini Omni Flash der einzige Anbieter im Angebot mit zustandsbehafteter Mehrfachdurchgangs-Bearbeitung. Siehe Layer 3 gemini-omni für die maßgebliche Prompt-Richtlinie (Referenzbild-Tags, Zeitcode-Syntax, Bearbeitungs-Prompt-Regeln), bevor Sie einen Prompt dafür schreiben.
Bevorzugte Premium-Standardauswahl – 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 Standardauswahl für kinoreife, Trailer- und hochauflösende Clip-Arbeiten. Es ist das einzige Modell im Angebot mit einmaligem Durchgangs-nativem synchronisiertem Audio, Mehrfachshot-Generierung, direkter Kamerasteuerung auf Regisseurebene und Lippen-Synchronisation aus zitierten Dialogen und liegt Anfang 2026 auf Platz 1 des Artificial Analysis Elo. Wechseln Sie nur davon ab, wenn der Benutzer einen bestimmten Grund hat (Budget, Anbieterpräferenz, stilistische Passung 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 Prompt- und Parameter-Richtlinie.
WICHTIG: Verwenden Sie immer video_selector anstatt Anbieter-Tools direkt aufzurufen. Der Selektor kümmert sich um Verfügbarkeitsprüfungen, Kostenvergleiche und automatisches Fallback, und seine Bewertungsengine bevorzugt bereits Seedance 2.0 für kinoreife Absichten.
Authentifizierung
Verwenden Sie dasjenige konfigurierte Gateway, das am besten zu den verfügbaren Anbietern des Benutzers und dessen Kosten-/Qualitätszielen passt.
- HeyGen: Setzen Sie
HEYGEN_API_KEY, um auf das Multi-Modell-Gateway zuzugreifen. - fal.ai: Setzen Sie
FAL_KEY, um über fal.ai auf Kling, MiniMax und Veo zuzugreifen. - Kling Official: Setzen Sie
KLING_API_KEY, um überprovider="kling_official"auf die offizielle Kling-Direct-API zuzugreifen. - Gemini API: Setzen Sie
GEMINI_API_KEYoderGOOGLE_API_KEY, um auf die Gemini Omni Video-Generierung und konversationelle Bearbeitung zuzugreifen.
Beschreiben Sie kein Gateway als Standard- oder Top-Auswahl, ohne zuvor das Register und die aktuelle Aufgabenpassung zu prüfen.
fal.ai Kling (kling_video, provider="kling") und Kling Official (kling_official_video, provider="kling_official") sind unterschiedliche Pfade. Verwenden Sie keine fal.ai-Warteschlangen-URLs, FAL_KEY oder Bild-Upload-Verhalten, 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 | Videogenerierungsanbieter (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 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"
}
}
}
Abfragen bis zur Fertigstellung
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
Einfacher 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, geringe Tiefenschärfe"
}
}'
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/produktfoto.png",
"provider": "kling_pro"
}
}
Hochformat für Soziale Medien
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Ein trendiges Café-Interieur, Kamera schwenkt langsam über die Theke",
"aspect_ratio": "9:16",
"provider": "veo_3_1"
}
}
Schnelle Generierung mit LTX
{
"workflow_type": "GenerateVideoNode",
"input": {
"prompt": "Abstrakte, farbenfrohe Formen, die sich verwandeln und fließen",
"provider": "ltx_distilled"
}
}
Best Practices
- Seien Sie beschreibend in Prompts – fügen Sie Details zu Kamerabewegung, Beleuchtung, Stil und Stimmung hinzu
- Standardmäßig Seedance 2.0 (über
seedance_video) für kinoreife und bewegungsgeführte Arbeiten verwenden, wennFAL_KEYgesetzt ist – einmaliges Durchgangs-synchronisiertes Audio, Mehrfachshots, Lippen-Synchronisation, Kamerasteuerung auf Regisseurebene. Verwenden Sie VEO 3.1 / Sora V2 Pro, wenn der Benutzer ausdrücklich Google- oder OpenAI-Bewegungscharakteristik wünscht; verwenden Sieltx_distilledoderveo3_fastnur, wenn Geschwindigkeit die harte Einschränkung ist - Verwenden Sie Referenzbilder für die 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 Social-Media-Stories/Reels,16:9für Querformat,1:1für Quadrat - Die 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