Avatar-Video
Erstelle KI-Avatar-Videos mit vollständiger Kontrolle über Avatare, Stimmen, Skripte, Szenen und Hintergründe. Baue 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"
Werkzeugauswahl
Falls HeyGen MCP-Werkzeuge verfügbar sind (mcp__heygen__*), bevorzuge sie gegenüber direkten HTTP-API-Aufrufen – sie kümmern sich automatisch um Authentifizierung und Anfrageformatierung.
| Aufgabe | MCP-Werkzeug | Fallback (Direkte API) |
|---|---|---|
| Videostatus prüfen / URL abrufen | mcp__heygen__get_video | GET /v2/videos/{video_id} |
| Kontovideos 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/Stimmen erfolgen über direkte API-Aufrufe – siehe 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→ Eine Stimme auswählen, die zum Geschlecht/Sprache des Avatars passt. Siehe voices.md - Skript schreiben – Szenen mit je 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 | Lies |
|---|---|
| Avatare auflisten und Vorschau anzeigen | avatars.md |
| Stimmen auflisten und auswählen | voices.md |
| Skripte schreiben und strukturieren | scripts.md |
| Video generieren (Einzel- oder Mehrszenenvideo) | video-generation.md |
| Benutzerdefinierte Hintergründe hinzufügen | backgrounds.md |
| Untertitel/Beschriftungen hinzufügen | captions.md |
| Texteinblendungen 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. Create Video 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 einfach nur eine Videoidee beschreiben und den Rest (Skript, Avatar, Bilder) der KI überlassen möchte, verwende stattdessen die create-video-Fähigkeit.
| Benutzer sagt | Create Video Fähigkeit | Diese Fähigkeit |
|---|---|---|
| "Mach mir ein Video über X" | ✓ | |
| "Erstelle eine Produktdemo" | ✓ | |
| "Ich möchte, dass Avatar Y genau Z sagt" | ✓ | |
| "Mehrszenenvideo mit unterschiedlichen Hintergründen" | ✓ | |
| "Transparentes WebM zum Compositing" | ✓ | |
| "Diese spezifische Stimme für mein Skript verwenden" | ✓ | |
| "Batch-Videos mit genauen Spezifikationen generieren" | ✓ |
Referenzdateien
Kernvideogenerierung
- references/avatars.md – Avatare auflisten, Stile, avatar_id-Auswahl
- references/voices.md – Stimmen auflisten, Sprachräume, Geschwindigkeit/Tonhöhe
- references/scripts.md – Skripte schreiben, Pausen, Taktung
- references/video-generation.md – POST /v2/video/generate und Mehrszenenvideos
Videoanpassung
- references/backgrounds.md – Einfarbige Hintergründe, Bilder, Videohintergründe
- references/text-overlays.md – Texteinblendungen mit Schriftarten und Positionierung
- references/captions.md – Automatische Untertitel
Erweiterte Funktionen
- references/templates.md – Vorlagen auflisten und Variablen 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 – 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 der Generierung in der Vorschau anzeigen – Lade
preview_image_urlherunter, damit der Benutzer den Avatar sehen kann, bevor er sich festlegt - Standardstimme des Avatars verwenden – Die meisten Avatare haben eine
default_voice_id, die für natürliche Ergebnisse voreingestellt ist - Fallback: Geschlecht manuell abgleichen – Falls keine Standardstimme vorhanden, stelle sicher, dass Avatar- und Stimmgeschlecht übereinstimmen
- Testmodus für die Entwicklung verwenden – Setze
test: true, um Guthaben zu sparen (Ausgabe enthält Wasserzeichen) - Großzügige Timeouts einstellen – Die Videogenerierung dauert oft 5–15 Minuten, manchmal länger
- Eingaben validieren – Prüfe, ob Avatar- und Stimm-IDs existieren, bevor du generierst