Was macht Avatar-Video?
Erstelle KI-Avatar-Videos mit vollständiger Kontrolle über Avatare, Stimmen, Skripte, Szenen und Hintergründe. Erstelle Einzel- oder Mehrszenenvideos mit genauer Konfiguration über HeyGens /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 |
| Ein Video löschen | mcp__heygen__delete_video | DELETE /v2/videos/{video_id} |
Die Videogenerierung (POST /v2/video/generate) und das Auflisten von Avataren/Stimmen erfolgen über direkte API-Aufrufe – siehe die Referenzdateien unten.
Standard-Workflow
- Avatare auflisten —
GET /v2/avatars→ Avatar auswählen, Vorschau anzeigen,avatar_idunddefault_voice_idnotieren. Siehe avatars.md - Stimmen auflisten (falls nötig) —
GET /v2/voices→ Stimme auswählen, die zum Geschlecht/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 Statuscompletedist. Siehe video-status.md
Kurzreferenz
| Aufgabe | Lesen |
|---|---|
| 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 |
| Bildunterschriften / Untertitel 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 dieses Skill im Vergleich zu Create Video verwenden
Dieses Skill ist für präzise Kontrolle gedacht – du wählst den Avatar, schreibst das exakte Skript, konfigurierst jede Szene.
Wenn der Nutzer einfach nur eine Videoidee beschreiben möchte und der Rest (Skript, Avatar, Visuals) von der KI erledigt werden soll, verwende stattdessen das create-video-Skill.
| Nutzer sagt | Create Video Skill | Dieses Skill |
|---|---|---|
| „Erstelle mir ein Video über X“ | ✓ | |
| „Erstelle eine Produktdemo“ | ✓ | |
| „Ich will, dass Avatar Y genau Z sagt“ | ✓ | |
| „Mehrszenenvideo mit verschiedenen Hintergründen“ | ✓ | |
| „Transparentes WebM für Compositing“ | ✓ | |
| „Verwende diese spezifische Stimme für mein Skript“ | ✓ | |
| „Generiere Videos in Serie mit exakten Spezifikationen“ | ✓ |
Referenzdateien
Kern-Videocreation
- references/avatars.md - Avatare auflisten, Stile, Auswahl von avatar_id
- references/voices.md - Stimmen auflisten, Sprachen, Geschwindigkeit/Tonhöhe
- references/scripts.md - Skripte schreiben, Pausen, Tempo
- references/video-generation.md - POST /v2/video/generate und Mehrszenenvideos
Videoanpassung
- 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 Bildunterschriften und Untertitel
Erweiterte Funktionen
- references/templates.md - Vorlagen auflisten und Variablenersetzung
- 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 - Abfragemuster und Download-URLs
- references/assets.md - Bilder, Videos, Audio hochladen
- references/dimensions.md - Auflösung und Seitenverhältnisse
- references/quota.md - Guthabensystem und Nutzungslimits
Best Practices
- Avatare vor dem Generieren in der Vorschau anzeigen — Lade
preview_image_urlherunter, damit der Nutzer den Avatar vor der Beauftragung sehen kann - Standardstimme des Avatars verwenden — Die meisten Avatare haben eine vorgegebene
default_voice_id, die für natürliche Ergebnisse optimiert ist - Fallback: Geschlecht manuell abgleichen — Falls keine Standardstimme vorhanden ist, stelle sicher, dass Avatar- und Stimmgeschlecht übereinstimmen
- Testmodus für die Entwicklung verwenden — Setze
test: true, um keine Credits zu verbrauchen (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 Stimm-IDs existieren, bevor die Generierung startet