Skripte mit der heygen-avatar-v- und hiapi-API in kurze Sprechervideos verwandeln

Kurzformatige Sprecherinhalte – Updates vom Gründer, Produktdemos, UGC-artige Werbespots – bedeuten normalerweise: echte Person buchen, Mikrofon aufbauen, danach noch einmal schneiden. heygen-avatar-v auf hiapi komprimiert all das in einen einzigen API-Aufruf: Skript oder Audiodatei senden und ein lippensynchrones Avatar-Video zurückbekommen, mit natürlichen Idle-Bewegungen und einer Untertitelspur, bereit für den Short-Video-Feed. Dieser Artikel geht den tatsächlichen /v1/tasks-Workflow durch, einen real generierten Clip, die Einschränkungen, die man kennen sollte, bevor man eine Pipeline darum baut, und die Preise, live aus hiapis /api/pricing gezogen. Wenn Sie Prompt-Techniken für den Stil des Avatars selbst suchen, deckt heygen-avatar-v prompt recipes das ab – hier geht es darum, das Modell in eine wiederverwendbare Short-Video-Pipeline einzubinden.

Was heygen-avatar-v tatsächlich ausgibt

heygen-avatar-v ist ein Digital-Human-Video-Modell, kein Text-zu-Video-Generator im Sinne von Sora/Kling – es treibt einen voreingestellten HeyGen-Avatar mit einem Textskript oder einer hochgeladenen Audiodatei an und liefert ein Video zurück, in dem der Mund des Avatars lippensynchron zur Stimme ist und dezente, kontinuierliche Bewegungen vorhanden sind (Blinzeln, leichte Kopfbewegungen, Schulterwippen), sodass es nicht wie ein statisches Porträt wirkt. Dieses „bewegt sich auch im Leerlauf"-Verhalten ist genau die Grenze zwischen einem brauchbaren Short-Video-Clip und einem auf den ersten Blick falschen sprechenden Foto.

Das Modell wird von zwei Eingaben gesteuert, die sich gegenseitig ausschließen – Sie senden die eine oder die andere:

• prompt – ein Textskript; wird von hiapis TTS vorgelesen und treibt die Lippensynchronisation an
• audio_url – eine öffentliche URL zu einer vorab aufgenommenen Tonspur (Ihre eigene Stimme, eine geklonte Stimme, egal was), die die Lippensynchronisation antreibt

Es gibt kein duration-Feld. Die Cliplänge hängt ganz davon ab, wie lange das Skript oder das Audio läuft – eine Zeile mit 40 Wörtern ergibt einen kürzeren Clip als eine mit 200 Wörtern. Das ist wichtig für die Kostenplanung, dazu unten mehr.

Optionale Felder dienen der Stilabstimmung: avatar (Auswahl aus der HeyGen-Preset-Bibliothek), voice (nur zusammen mit prompt verwendet, bei audio_url ignoriert), aspect_ratio (9:16 für Reels/TikTok/Shorts, 16:9, 1:1), resolution, background (einfarbig oder Szene – aber siehe die Stolperfalle unten), caption (erzeugt eine Untertitelspur) sowie output_format (mp4 oder webm, letzteres mit transparentem Hintergrund zur Komposition in eigene Szenen).

Echter Clip: Skript rein, Avatar-Video mit Untertiteln raus

Hier ist eine tatsächliche heygen-avatar-v-Ausgabe – der Avatar spricht eine Skriptzeile, mit sichtbaren Idle-Bewegungen zwischen den Phrasen und einer synchronen Untertitelspur:

Beachten Sie, was nicht passiert: Der Avatar erstarrt nicht zwischen den Sätzen, und die Untertitel folgen der Sprache, statt nachträglich aufgeklebt zu werden. Diese Kombination – durchgehende Bewegung plus zeitlich abgestimmte Untertitel – ist der ganze Grund, dieses Modell zu wählen, statt in einem Editor ein statisches Avatar-Bild mit einer Erzählstimme zu unterlegen.

Stolperfallen: zwei Probleme, die eine erste Pipeline beißen

caption liefert eine Untertitel-Begleitdatei, keine eingebrannten Untertitel. caption: true gibt zusätzlich zur Videoausgabe eine synchrone .srt-Datei zurück – es brennt den Text nicht in die Videoframes ein. Wenn Sie den Untertiteltext auf dem Bildschirm wollen (der Look, den die meisten Short-Video-Plattformen haben), müssen Sie mit dieser .srt-Datei separat ein Burning durchführen (ffmpeg -i clip.mp4 -vf subtitles=captions.srt output.mp4 oder die native Untertitel-Importfunktion Ihrer Plattform nutzen). Behandeln Sie die „Untertitel" der API als Daten, nicht als fertig gerendertes Bild.

background wirkt nur bei Illustrations-Avataren, nicht bei fotorealistischen. Die HeyGen-Avatarbibliothek mischt fotorealistische Avatar-Videos mit illustrierten/animiterten Avataren. Der Parameter background ersetzt erfolgreich die Szene hinter einem Illustrations-Avatar, aber fotorealistische Avatare behalten ihren ursprünglich aufgenommenen Hintergrund, egal was Sie übergeben – das Modell schneidet ihn nicht aus. Wenn Ihre Pipeline annimmt, dass jeder Avatar eine Hintergrundüberlagerung akzeptiert, testen Sie zuerst die konkrete avatar-ID, die Sie verwenden wollen, bevor Sie davon ausgehen, dass sie sich wie erwartet komponieren lässt. Für fotorealistische Avatare, die Sie vor Ihren eigenen Hintergrund setzen wollen, ist der verlässliche Weg output_format: webm (transparent).

Kosten: Abrechnung nach Ausgabesekunden, nicht nach Aufrufen

Laut hiapis Live-/api/pricing wird heygen-avatar-v mit $0,15 pro Ausgabesekunde abgerechnet – einheitlicher Tarif unabhängig von Auflösung oder Seitenverhältnis. Da es keine Dauer-Eingabe gibt, hängen Ihre tatsächlichen Kosten davon ab, wie lange das Skript oder Audio läuft:

Skriptlänge (ca.)	Ausgabedauer	Kosten
Kurzer Hook-Satz	ca. 5 Sekunden	$0,75
Ein Short-Video-Beat	ca. 10 Sekunden	$1,50
Mehrsätzlicher Pitch	ca. 20 Sekunden	$3,00
Vollständiger 30-Sekunden-Werbespot	ca. 30 Sekunden	$4,50

Da die Kosten mit der Sprachlänge skalieren und nicht mit einem vorab festgelegten Parameter, ist die praktische Vorgehensweise, das Skript vor dem Absenden des Tasks zu timen (einmal vorlesen oder einen TTS-Längenabschätzer laufen lassen), statt erst nach dem Rendern des Clips die Rechnung zu bemerken.

Pipeline: Absenden, Abfragen, vor dem Ablaufen herunterladen

heygen-avatar-v läuft auf hiapis asynchronem /v1/tasks-Endpunkt – wie alle anderen task-basierten Modelle der Plattform im Muster „erst erstellen, dann abfragen". Ein Detail, das für diesen Workflow spezifisch ist: Tasks durchlaufen zwischen handling und success eine archiving-Phase, in der die Plattform das Video und die Untertitel-Begleitdatei fertigstellt, also behandeln Sie archiving in Ihrer Polling-Schleife nicht als Endzustand.

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_avatar_video(script: str, avatar: str, aspect_ratio: str = "9:16") -> str:
    payload = {
        "model": "heygen-avatar-v",
        "input": {
            "prompt": script,
            "avatar": avatar,
            "aspect_ratio": aspect_ratio,
            "caption": True,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_video(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        status = task["status"]
        if status == "success":
            return task["output"]  # [{"url": "...mp4"}, {"url": "...srt"}] — download both, now
        if status == "failed":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        # "handling" and "archiving" are both non-terminal — keep polling
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_avatar_video(
        script="Here's the thirty-second version of what we shipped this week.",
        avatar="your-avatar-id",
    )
    outputs = wait_for_video(task_id)
    print("outputs:", outputs)

Zwei Betriebshinweise, die man beim Einsatz in großem Maßstab nicht überspringen darf:

• Sofort herunterladen. Wie bei jeder Task-Ausgabe auf hiapi tragen die zurückgegebenen URLs ein expireAt und taugen nicht als Langzeitlinks – sobald der Task erfolgreich ist, ziehen Sie die Bytes (Video und .srt) in Ihren eigenen Speicher.
• Senden Sie keine Payload mit nur den Minimalfeldern, nur um „das Schema zu prüfen". Da streng genommen nur prompt oder audio_url erforderlich sind und alle anderen Felder stillschweigend Standardwerte nutzen, gibt eine Payload wie {"prompt": "test"} keinen 400-Fehler zurück – sie löst ein echtes, abrechenbares Rendering aus. Validieren Sie Feldnamen anhand der Dokumentation oder mit einem absichtlich ungültigen Wert, der eine 4xx-Antwort erzeugt, statt Felder gegen den echten Endpunkt wegzulassen.

FAQ

Kann ich meine eigene Stimme statt hiapis TTS verwenden? Ja – übergeben Sie audio_url statt prompt mit einer öffentlichen URL Ihrer Aufnahme, und der Avatar synchronisiert die Lippen zu dieser Tonspur, statt Sprache aus Text zu synthetisieren.

Brennt die caption-Option Untertitel ins Video ein? Nein. caption: true gibt eine separate .srt-Datei zurück, die mit dem Audio des Ausgabevideos synchronisiert ist. Wenn Sie den Untertiteltext auf dem Bildschirm wollen, brennen Sie ihn selbst als Nachbearbeitungsschritt ein.

Kann ich die Cliplänge steuern? Nicht direkt – es gibt keinen duration-Parameter. Die Ausgabelänge richtet sich nach der Skriptlänge (bei Verwendung von prompt) oder nach der Länge der Audiodatei (bei Verwendung von audio_url).

Warum erscheint der von mir angegebene Hintergrund nicht? background wirkt nur bei illustrierten/animiterten Avataren aus der HeyGen-Bibliothek. Fotorealistische, fotoähnliche Avatare behalten ihren ursprünglich aufgenommenen Hintergrund; nutzen Sie hier stattdessen output_format: webm, um eine transparente Ausgabe zu erhalten und die Komposition selbst zu übernehmen.

Welche Auflösungen und Seitenverhältnisse werden unterstützt? Bis zu 4K, mit Optionen für die Seitenverhältnisse 9:16, 16:9 und 1:1 – von vertikalen Short-Video-Feeds bis zu Breitbild- und quadratischen Platzierungen.

Fazit

Eine Short-Video-Avatar-Pipeline auf hiapi aufzubauen läuft auf einige konkrete Fakten hinaus statt auf Vermutungen: Die Kosten liegen bei $0,15 pro Ausgabesekunde (also das Skript vor dem Absenden timen, nicht danach), die Untertitelausgabe ist eine .srt-Begleitdatei, die Sie selbst einbrennen müssen, der Hintergrundersatz funktioniert nur bei Illustrations-Avataren, und Ihre Polling-Schleife muss archiving genauso wie handling als nicht-terminal behandeln. Bevor Sie ein Budget fest verdrahten, prüfen Sie die aktuellen Zahlen auf hiapis Preisseite, die vollständige Feldreferenz finden Sie auf der Modellseite. Wenn Sie bereit sind loszulegen, holen Sie sich einen API key aus dem Dashboard und starten Sie mit einem kurzen Skript – eine 5-Sekunden-Ausgabe reicht, um zu bestätigen, dass Ihr Avatar, das Seitenverhältnis und die Untertitelverarbeitung funktionieren, bevor Sie auf ganze Chargen hochskalieren.