HeyGen MP3 → MP4 (Einzelzweck)
Nimm eine MP3-Sprachaufnahme, gib ein HeyGen-Avatar-Lip-Sync-MP4 zurück. Nichts weiter.
Dieses Skill existiert, weil das vorhandene heygen-short-video-Skill einen vollständigen Produktionsplan + SRT + segmentierte Teile erfordert – übertrieben, wenn der Benutzer nur eine fertige Sprachaufnahme hat und ein Talking-Head-Video möchte.
Warum hybrider REST + MCP (nicht nur MCP)
Frühere Versionen dieses Skills bestanden auf "Nur MCP – niemals REST aufrufen." Diese Regel ist nicht mehr machbar seit der Neugestaltung des HeyGen MCP (2026): Der MCP-Server stellt nur noch create_video_from_avatar, get_video, create_lipsync, list_avatar_looks usw. bereit – es gibt kein Tool zum Hochladen von Assets mehr. Für Lip-Sync von einer lokalen MP3 benötigt die API jedoch entweder eine audioAssetId (hochgeladenes Asset) oder eine audioUrl (öffentliche HTTPS-URL). Das Hosten einer öffentlichen URL ist instabil (Link-Rot, Datenlecks), daher verwenden wir den dokumentierten REST-Upload-Endpunkt über ein dünnes Hilfsskript und fahren dann über MCP mit der Videoerstellung, dem Abfragen und dem Herunterladen fort.
Harte Einschränkungen
| Einschränkung | Erlaubte Werte |
|---|---|
| Asset-Upload | REST POST https://upload.heygen.com/v1/asset über scripts/upload_asset.py (verwendet HEYGEN_API_KEY) |
| Videoerstellung / Status / Liste | Nur HeyGen MCP (mcp__heygen__create_video_from_avatar, mcp__heygen__get_video) |
| Avatar-Look-ID | Eine der IDs in der Umgebungsvariable HEYGEN_AVATAR_LOOKS (Komma-getrennte Erlaubnisliste) |
| Sprach-ID (nur wenn der MCP-Pfad TTS erzwingt) | HEYGEN_VOICE_ID aus .env (keine andere Sprach-ID ist erlaubt) |
| MP3-Dauer | ≤ 300 Sekunden (5 Minuten). Bei Überschreitung sofort abbrechen; nicht automatisch aufteilen |
| Seitenverhältnis (MCP-Enum) | Standard 9:16 (TikTok / Reels). Nur 16:9 wenn der übergeordnete Orchestrator dies überschreibt |
| Auflösung (MCP-Enum) | Standard 720p (ergibt 720×1280 für 9:16, 1280×720 für 16:9) |
Für MP3-Lip-Sync ist der Sprachtyp audio und audioAssetId wird bereitgestellt – voiceId wird nicht gesendet. Die obige Sprach-ID-Erlaubnisliste ist nur relevant, wenn eine zukünftige MCP-Signatur eine erfordert.
Eingaben
- MP3-Pfad (erforderlich) – absoluter Pfad zur Sprachdatei.
- Avatar-Look-ID (optional) – eine der erlaubten IDs. Wenn nicht angegeben, wähle zufällig aus dem erlaubten Satz, um visuelle Abwechslung über mehrere Läufe hinweg zu erzielen.
- Ausgabepfad (optional) – Standard ist
workspace/heygen-clips/<mp3-stem>/<mp3-stem>_<YYYYMMDD-HHMMSS>.mp4relativ zum Projektstamm. - Seitenverhältnis (optional) –
9:16(Standard) oder16:9.
Arbeitsablauf
Befolge diese Schritte der Reihe nach. Jeder Schritt hat eine Abbruchbedingung; fahre nicht fort, wenn ein Schritt fehlschlägt.
0. Authentifizierungsprüfung (nur beim ersten Aufruf)
Der HeyGen MCP-Server verwendet OAuth. In einer neuen Sitzung sind nur mcp__heygen__authenticate und mcp__heygen__complete_authentication verfügbar; die eigentlichen Tools (create_video_from_avatar, get_video, …) erscheinen nach Abschluss der Authentifizierung. Wenn die Sitzung keines dieser Tools geladen hat, rufe mcp__heygen__authenticate auf und zeige dem Benutzer die zurückgegebene Autorisierungs-URL an. Der Benutzer klickt → der Browser zeigt möglicherweise einen "Verbindungsfehler" beim localhost-Callback an (dies ist zu erwarten) → der Benutzer fügt die vollständige Callback-URL zurück ein, du rufst mcp__heygen__complete_authentication auf. Sobald die Tools nach der Authentifizierung in der Liste der zurückgestellten Tools erscheinen, fahre fort.
1. MP3 validieren
uv run .claude/skills/heygen-mp3-to-mp4/scripts/check_duration.py "<mp3_path>"
Gibt OK <Sekunden> / TOO_LONG <Sekunden> / MISSING aus. Exit-Code 0 = OK, nicht Null = abbrechen.
Wenn TOO_LONG: Teile dem Benutzer die Dauer mit und dass HeyGen ein einzelnes Video auf ca. 5 Minuten begrenzt, und empfehle das vorhandene heygen-short-video-Skill (das Chunking verwendet). Fahre nicht fort.
2. Avatar-Look auswählen
Lese HEYGEN_AVATAR_LOOKS (Komma-getrennte Erlaubnisliste):
HEYGEN_AVATAR_LOOKS=$(
grep -h '^HEYGEN_AVATAR_LOOKS=' .env.local .env 2>/dev/null \
| head -1 | cut -d'=' -f2- | tr -d '"' | tr -d "'"
)
echo "$HEYGEN_AVATAR_LOOKS" | tr ',' '\n' | awk 'BEGIN{srand()} {a[NR]=$0} END{print a[int(rand()*NR)+1]}'
Platzhalterfalle – claudeclaw-os/.env.local enthält Platzhalter-Stubs (avatar_look_id_1,avatar_look_id_2). Die echten Werte befinden sich oft in ~/Documents/GitHub/hoang-ai-marketing/.env:
grep '^HEYGEN_AVATAR_LOOKS=' ~/Documents/GitHub/hoang-ai-marketing/.env
Wenn der Wert mit ^(your_|avatar_look_id_|placeholder) übereinstimmt, behandle ihn als fehlend und greife auf die .env des Marketing-Repositorys zurück. Wenn beide Platzhalter/fehlend sind, stoppe und bitte den Benutzer, echte IDs einzufügen.
Teile dem Benutzer vor dem Fortfahren mit, welcher Avatar-Look ausgewählt wurde – er möchte ihn möglicherweise überschreiben.
3. MP3 als HeyGen-Asset hochladen (REST)
uv run .claude/skills/heygen-mp3-to-mp4/scripts/upload_asset.py "<mp3_path>"
# → gibt bei Erfolg "OK <asset_id>" aus
Das Hilfsskript verarbeitet den X-Api-Key-Header, wählt den richtigen Content-Type für die Audio-Erweiterung und löst HEYGEN_API_KEY in dieser Reihenfolge auf: --key-file-Flag → HEYGEN_API_KEY env → .env.local → .env → ~/Documents/GitHub/hoang-ai-marketing/.env. Platzhalter-Stubs (your_*) werden automatisch übersprungen.
Erfasse die auf stdout ausgegebene asset_id.
4. Avatar-Video generieren (MCP)
Rufe mcp__heygen__create_video_from_avatar mit dem neuen Schema auf (die alte dimension: {width, height}-Form gibt es nicht mehr – das Tool verwendet jetzt das aspectRatio-Enum + resolution-Enum):
avatarId: <aus der Erlaubnisliste ausgewählt>
audioAssetId: <aus Schritt 3>
aspectRatio: "9:16" # oder "16:9" wenn vom übergeordneten Orchestrator überschrieben
resolution: "720p" # 720p · 1080p · 4k
title: "<mp3-stem>-<Zeitstempel>"
Erfasse die zurückgegebene video_id (Status ist anfangs waiting).
Warum Audio (nicht Text): Lip-Sync von einer vorhandenen MP3 erfordert, dass HeyGen das Audio direkt verarbeitet. Das Senden eines script + voiceId würde HeyGen in den TTS-Modus versetzen und die hochgeladene MP3 vollständig ignorieren.
5. Abfragen bis zur Fertigstellung
Rufe mcp__heygen__get_video mit der video_id alle ~10–15 Sekunden auf. Status:
waiting/processing/pending→ weiter abfragencompleted→video_urlaus der Antwort holen und fortfahrenfailed→ stoppen,failure_messagedem Benutzer anzeigen
Begrenze die Wartezeit auf ca. 10 Minuten; wenn noch in Bearbeitung, informiere den Benutzer und lass ihn entscheiden.
zsh-Quirk für Abfrageschleifen – der Variablenname status ist in zsh schreibgeschützt. Wenn du status=$(…) in einer Abfrageschleife schreibst, stürzt das Skript mit read-only variable: status ab. Verwende einen anderen Namen (vstate, phase, ready).
6. MP4 herunterladen
uv run .claude/skills/heygen-mp3-to-mp4/scripts/download_video.py "<video_url>" "<output_path>"
Einfacher HTTPS-Download der von HeyGen zurückgegebenen URL – kein API-Aufruf zum Erstellen oder Ändern eines Videos.
7. Rückmeldung geben
Teile dem Benutzer drei Dinge in einer kurzen Antwort mit:
- Ausgabepfad des MP4
- Welcher Avatar-Look verwendet wurde
- Dauer und Dateigröße des Ergebnisses
Beispiel
Benutzer: tạo video heygen từ mp3 workspace/audio/episode-3.mp3
Du:
- Authentifizierungsprüfung → wenn HeyGen-Tools vorhanden, überspringe; sonst
mcp__heygen__authenticate+ OAuth-Ablauf abschließen. check_duration.py workspace/audio/episode-3.mp3→OK 87.4- Zufällige Auswahl aus
HEYGEN_AVATAR_LOOKS(z.B.66e75e22e6584bbdaa56a19088286dc8). Sage es. upload_asset.py workspace/audio/episode-3.mp3→OK 36922ca92326480f8dbb0f57fae1a144mcp__heygen__create_video_from_avatar(avatarId=…, audioAssetId=…, aspectRatio="9:16", resolution="720p", title="episode-3-…")→video_id: 874793a8…mcp__heygen__get_videoalle ~15s abfragen biscompleted→video_urlholendownload_video.py <url> workspace/heygen-clips/episode-3/episode-3_20260510-143022.mp4- Pfad, Look-ID, Dauer melden.
Was dieses Skill bewusst NICHT tut
- Schreibt/transkribiert kein SRT (das macht
mkt-ai-video-extract-srt-segment). - Plant keine Bilder, B-Roll, Segmente (das macht
mkt-plan-short-video-edit-16-9). - Teilt keine MP3 auf (das macht
heygen-short-videomitsplit_audio.py). - Führt kein Compositing mit Remotion oder HyperFrames durch (das macht der übergeordnete Orchestrator).
Wenn der Benutzer eines der oben genannten wünscht, verweise ihn auf das entsprechende Skill, anstatt dieses zu erweitern.
Fehlermodi und Meldungen
| Symptom | Was dem Benutzer sagen |
|---|---|
| MP3-Datei fehlt | MP3 nicht gefunden unter <path>. Überprüfe den Pfad. |
| MP3 > 300s | MP3 ist <X>s lang, überschreitet das Limit von 5 Minuten von HeyGen. Verwende stattdessen das Skill heygen-short-video (mit Chunking). |
| HeyGen MCP nicht authentifiziert | Zeige mcp__heygen__authenticate-URL, bitte Benutzer zu autorisieren, dann mcp__heygen__complete_authentication. |
HEYGEN_API_KEY nicht gefunden / Platzhalter | HEYGEN_API_KEY nicht gefunden. Das Hilfsskript hat .env.local, .env und ~/Documents/GitHub/hoang-ai-marketing/.env durchsucht. Du musst einen echten Key (keinen Stub your_*) in einer dieser Dateien hinzufügen. |
HEYGEN_AVATAR_LOOKS ist Platzhalter (avatar_look_id_1,…) | Gleicher Fallback wie beim API-Key – aus dem Marketing-Repository lesen oder Benutzer bitten, echte Avatar-IDs einzufügen. |
| HeyGen gibt Fehlschlag zurück | HeyGen-Rendering fehlgeschlagen: <failure_message>. Möglicherweise wurde der Avatar-Look gelöscht oder das Audio-Asset ist ungültig. |
| Guthaben aufgebraucht | Den Fehler von HeyGen anzeigen – es gibt in dieser Serverversion kein MCP get_remaining_credits. Leite den Benutzer an https://app.heygen.com/billing weiter. |
Toolname nicht gefunden (upload_asset / generate_avatar_video / get_avatar_video_status) | Alte MCP-Namen – ersetzt durch REST-Upload + create_video_from_avatar + get_video. Aktualisiere jeden Aufrufer, der noch die alten Namen verwendet. |