Avatar-Video
Erstelle KI-Avatar-Videos mit vollständiger Kontrolle über Avatare, Stimmen, Skripte, Szenen und Hintergründe. Baue Einzel- oder Mehrszenen-Videos mit exakter Konfiguration mittels der HeyGen /v2/video/generate API.
Authentifizierung
Alle Anfragen benötigen den X-Api-Key-Header. Setze die Umgebungsvariable HEYGEN_API_KEY.
curl -X GET "https://api.heygen.com/v2/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Tool-Auswahl
Falls HeyGen MCP-Tools verfügbar sind (mcp__heygen__*), bevorzuge sie gegenüber direkten HTTP-API-Aufrufen – sie übernehmen Authentifizierung und Anfrageformatierung automatisch.
| Aufgabe | MCP-Tool | Fallback (Direkte API) |
|---|---|---|
| Videostatus prüfen / URL abrufen | mcp__heygen__get_video | GET /v2/videos/{video_id} |
| Konto-Videos auflisten | mcp__heygen__list_videos | GET /v2/videos |
| Video löschen | mcp__heygen__delete_video | DELETE /v2/videos/{video_id} |
Die Videogenerierung (POST /v2/video/generate) sowie das Auflisten von Avataren und Stimmen erfolgen über direkte API-Aufrufe – siehe die Referenzdateien unten.
Standard-Workflow
- Avatare auflisten –
GET /v2/avatars→ Avatar auswählen, Vorschau ansehen,avatar_idunddefault_voice_idnotieren. Siehe avatars.md - Stimmen auflisten (falls nötig) –
GET /v2/voices→ Eine Stimme auswählen, die zum Geschlecht/der Sprache des Avatars passt. Siehe voices.md - Skript schreiben – Szenen mit jeweils einem Konzept strukturieren. Siehe scripts.md
- Video generieren –
POST /v2/video/generatemit Avatar, Stimme, Skript und Hintergrund pro Szene. Siehe video-generation.md - Auf Fertigstellung warten –
GET /v2/videos/{video_id}bis der Statuscompletedist. Siehe video-status.md
Kurzreferenz
| Aufgabe | Lese |
|---|---|
| Avatare auflisten und Vorschau anzeigen | avatars.md |
| Stimmen auflisten und auswählen | voices.md |
| Skripte schreiben und strukturieren | scripts.md |
| Video generieren (Einzel- oder Mehrszenen) | video-generation.md |
| Benutzerdefinierte Hintergründe hinzufügen | backgrounds.md |
| Untertitel / Übersetzungen hinzufügen | captions.md |
| Textüberlagerungen hinzufügen | text-overlays.md |
| Transparentes WebM-Video erstellen | video-generation.md (WebM-Abschnitt) |
| Vorlagen verwenden | templates.md |
| Avatar aus Foto erstellen | photo-avatars.md |
| Videostatus prüfen / herunterladen | video-status.md |
| Assets hochladen (Bilder, Audio) | assets.md |
| Mit Remotion verwenden | remotion-integration.md |
| Webhooks einrichten | webhooks.md |
Wann diese Fähigkeit vs. „Video erstellen“ verwenden
Diese Fähigkeit ist für präzise Kontrolle – du wählst den Avatar aus, schreibst das exakte Skript, konfigurierst jede Szene.
Wenn der Benutzer lediglich eine Videoidee beschreiben möchte und den Rest (Skript, Avatar, visuelle Elemente) der KI überlassen will, verwende stattdessen die Fähigkeit create-video.
| Benutzer sagt | Create-Video-Fähigkeit | Diese Fähigkeit |
|---|---|---|
| „Erstelle mir ein Video über X“ | ✓ | |
| „Erstelle eine Produktdemo“ | ✓ | |
| „Ich möchte, dass Avatar Y genau Z sagt“ | ✓ | |
| „Mehrszenen-Video mit unterschiedlichen Hintergründen“ | ✓ | |
| „Transparentes WebM für Compositing“ | ✓ | |
| „Verwende diese spezifische Stimme für mein Skript“ | ✓ | |
| „Batch-Generierung von Videos mit exakten Spezifikationen“ | ✓ |
Referenzdateien
Kernfunktionen zur Videoerstellung
- references/avatars.md – Avatare auflisten, Stile, avatar_id-Auswahl
- references/voices.md – Stimmen auflisten, Locales, Geschwindigkeit/Tonhöhe
- references/scripts.md – Skripte schreiben, Pausen, Tempo
- references/video-generation.md – POST /v2/video/generate und Mehrszenen-Videos
Video-Anpassung
- references/backgrounds.md – Einfarbige Hintergründe, Bilder, Videohintergründe
- references/text-overlays.md – Text mit Schriftarten und Positionierung hinzufügen
- references/captions.md – Automatisch generierte Untertitel und Übersetzungen
Erweiterte Funktionen
- references/templates.md – Vorlagen auflisten und Variable ersetzen
- references/photo-avatars.md – Avatare aus Fotos erstellen
- references/webhooks.md – Webhook-Endpunkte und Ereignisse
Integration
- references/remotion-integration.md – HeyGen in Remotion-Kompositionen verwenden
Grundlagen
- references/video-status.md – Polling-Muster und Download-URLs
- references/assets.md – Bilder, Videos, Audio hochladen
- references/dimensions.md – Auflösung und Seitenverhältnisse
- references/quota.md – Creditsystem und Nutzungslimits
Best Practices
- Avatare vor der Generierung in der Vorschau anzeigen – Lade
preview_image_urlherunter, damit der Benutzer den Avatar vor der Festlegung sehen kann - Standardstimme des Avatars verwenden – Die meisten Avatare haben eine vorab zugeordnete
default_voice_idfür natürliche Ergebnisse - Fallback: Geschlecht manuell abgleichen – Falls keine Standardstimme vorhanden ist, stelle sicher, dass Avatar- und Stimmen-Geschlecht übereinstimmen
- Testmodus für die Entwicklung verwenden – Setze
test: true, um Credits zu sparen (Ausgabe wird mit Wasserzeichen versehen) - Großzügige Timeouts setzen – Die Videogenerierung dauert oft 5–15 Minuten, manchmal länger
- Eingaben validieren – Überprüfe, ob Avatar- und Stimmen-IDs vor der Generierung existieren