Wie verwende ich die HeyGen Avatar V API? Von der Avatar-Auswahl bis zum fertigen Video

Bei HeyGen Avatar V wählen Sie einen vordefinierten digitalen Menschen, geben ein Skript oder Audio ein und erzeugen so ein Video mit Lippensynchronisation. HiAPI berechnet nach Ausgabedauer, $0.15 pro Sekunde, ein 10-Sekunden-Video kostet $1.50.

HeyGen Avatar V ist jetzt auf HiAPI verfügbar. Öffnen Sie die Modellseite, wählen Sie zuerst Avatar und Stimme und binden Sie dann die API ein. Das folgende Business-Erklärvideo ist ein fertiges Ergebnis:

Brandon Office Sitting Front, Dexter - Professional; 16:9, fertiges Video 1280×720, ca. 8 Sekunden. Die ursprüngliche Anfrage war 1080p, diese Seite zeigt die 720p-Webversion.

Hi, I'm Daniel. Send me your quarterly numbers, and I'll walk your team through what changed and what to do next.

Mit diesem Prompt generieren → Das Skript ist bereits eingetragen; wählen Sie oben manuell Avatar, Stimme, 1080p und 16:9, Ausgabe MP4.

Wie testet man es online?

1. Öffnen Sie den vorausgefüllten Link und behalten Sie dieses kurze Skript bei.
2. Wählen Sie Avatar und Stimme; diese Parameter müssen manuell gewählt werden, der Link übernimmt nur das Skript.
3. Legen Sie Seitenverhältnis, Auflösung und Format fest; für den ersten Versuch eignet sich die obige Kombination.
4. Hören Sie nach der Generierung die Vertonung an, prüfen Sie die Lippensynchronisation, laden Sie das fertige Video herunter und ersetzen Sie dann den Text durch Ihren eigenen.

Notieren Sie sich Avatar, Stimme und Seitenverhältnis dieses Tests und verwenden Sie sie bei der Batch-Generierung weiter; tauschen Sie nur das Skript aus, so bleiben Darsteller und Stimme konsistent.

V wählt den Darsteller aus vordefinierten Avataren; wenn Ihr eigenes Foto auftreten soll, wählen Sie Avatar IV.

Alle Auflösungen werden nach tatsächlichen Ausgabesekunden berechnet, bei Fehlschlag wird vollständig erstattet; die vollständigen Kosten finden Sie in der Preis- und Budgettabelle.

Was muss für die API vorbereitet werden?

Erstellen Sie einen API key in der Konsole. Geben Sie in der Anfrage ausdrücklich model und das erforderliche input.avatar an und wählen Sie dann eines von prompt und audio_url. Verwenden Sie für Avatar und Stimme die englischen Request-Werte aus den Dokumentationskarten; die chinesischen Namen dienen nur zur Identifikation.

Das Skript wird direkt vorgelesen; Kameraanweisungen gehören nicht in prompt. Bei Audio-Steuerung übergeben Sie eine erreichbare HTTP(S)-Adresse und entfernen prompt und voice. duration muss nicht übergeben werden; die Dauer ergibt sich aus dem Vorlesen des Skripts oder dem Audio.

Was Sie haben	Welche Steuerfelder Sie übergeben
Ein vorzulesendes Skript	avatar + prompt; voice optional
Bereits aufgenommene Stimme	avatar + audio_url; prompt und voice weglassen

Avatar-Lookup: Parameterdokumentation → Digitale Avatare, alles aufklappen, suchen und den englischen „Request value“ kopieren; die Stimme finden Sie ebenso unter Vordefinierte Stimmen. Auf der englischen Seite entspricht das Request value; setzen Sie keine chinesischen Anzeigenamen in die Anfrage.

**Minimale vollständige Audio-Anfrage:** Ersetzen Sie die Platzhalteradresse durch Ihre eigene öffentlich erreichbare Audio-URL. Weggelassene Seitenverhältnisse, Auflösungen und Formate verwenden die Dokumentationsstandardwerte; Audio max. 600 Sekunden, max. 32 MiB.

{
  "model": "heygen-avatar-v",
  "input": {
    "avatar": "Brandon Office Sitting Front",
    "audio_url": "https://example.com/your-recording.mp3"
  }
}

Aufgaben mit cURL erstellen und abfragen

Ersetzen Sie den Key-Platzhalter durch Ihren Wert; diese Anfrage übernimmt die Parameter des Business-Beispiels:

export HIAPI_API_KEY="sk-YOUR_KEY"
curl --fail-with-body --connect-timeout 10 --max-time 60 \
  -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-v",
    "input": {
      "avatar": "Brandon Office Sitting Front",
      "prompt": "Hi, I\u0027m Daniel. Send me your quarterly numbers, and I\u0027ll walk your team through what changed and what to do next.",
      "voice": "Dexter - Professional",
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "caption": false,
      "output_format": "mp4"
    }
  }'

Prüfen Sie den HTTP-Status und code im JSON; nach erfolgreicher Erstellung speichern Sie data.taskId. Fragen Sie anschließend nur dieselbe Aufgabe ab:

TASK_ID="REPLACE_WITH_data.taskId"
curl --fail-with-body --connect-timeout 10 --max-time 60 \
  "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

queued, handling, archiving bedeuten Verarbeitung; Endzustände sind success oder fail. Suchen Sie nach Erfolg anhand data.output[].type nach video und, wenn Untertitel aktiviert sind, nach caption. Lesen Sie die Artefakt-url und laden Sie sie rechtzeitig gemäß expireAt herunter.

**Beispiel für die Antwortstruktur:** Der erste Block ist die erfolgreiche Erstellung, der zweite die erfolgreiche Abfrage mit aktivierten Untertiteln; Aufgaben-ID, URLs und Ablaufzeit sind beispielhafte Werte; expireAt ist eine Zahl in Unix-Sekunden. Bei POST-Timeout oder verlorener Antwort prüfen Sie zuerst den Aufgabenrecord und wiederholen auf keinen Fall blind POST; mit einer ID setzen Sie GET fort.

{
  "code": 200,
  "data": {"taskId": "TASK_ID_FROM_CREATE"}
}

{
  "code": 200,
  "data": {
    "taskId": "TASK_ID_FROM_CREATE",
    "status": "success",
    "output": [
      {"type": "video", "url": "https://example.com/result.mp4", "expireAt": 4070908800},
      {"type": "caption", "url": "https://example.com/result.srt", "expireAt": 4070908800}
    ]
  }
}

Python: Erstellen, begrenztes Polling, Herunterladen

Installieren Sie zuerst requests und setzen Sie den Key in der Umgebungsvariable HIAPI_API_KEY. Der Code übermittelt nur einmal und pollt maximal 30 Minuten; bei Timeout behalten Sie die Aufgaben-ID und fragen weiter ab.

import os
import time
from pathlib import Path
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
payload = {
    "model": "heygen-avatar-v",
    "input": {
        "avatar": "Brandon Office Sitting Front",
        "prompt": "Hi, I'm Daniel. Send me your quarterly numbers, and I'll walk your team through what changed and what to do next.",
        "voice": "Dexter - Professional",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
        "caption": False,
        "output_format": "mp4",
    },
}

def api_request(method, url, **kwargs):
    advice = (
        "Submission state may be unknown; check task history before another POST."
        if method == "POST"
        else f"Continue GET with the saved task ID: {url.rsplit('/', 1)[-1]}."
    )
    try:
        response = requests.request(
            method, url, headers=HEADERS, timeout=(10, 30), **kwargs
        )
    except requests.RequestException:
        raise RuntimeError(f"Network error. {advice}") from None
    if not response.ok:
        raise RuntimeError(f"HTTP {response.status_code}. {advice}")
    try:
        body = response.json()
    except ValueError:
        raise RuntimeError(f"Response is not JSON. {advice}") from None
    if not isinstance(body, dict):
        raise RuntimeError(f"Unexpected response shape. {advice}")
    if body.get("code") != 200 or not isinstance(body.get("data"), dict):
        raise RuntimeError(f"API error: code={body.get('code')}. {advice}")
    return body["data"]

# Submit once. No automatic POST retries.
created = api_request("POST", API, json=payload)
task_id = created.get("taskId")
if not isinstance(task_id, str) or not task_id:
    raise RuntimeError("Missing taskId; check task history before resubmitting.")
print("taskId:", task_id)  # Keep this ID to resume GET queries.
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    data = api_request("GET", f"{API}/{task_id}")
    status = data.get("status")
    if status == "fail":
        raise RuntimeError(f"Task failed: {task_id}; inspect its task record.")
    if status == "success":
        break
    if status not in ("queued", "handling", "archiving"):
        raise RuntimeError(f"Unexpected task status: {status}")
    time.sleep(8)
else:
    raise TimeoutError(f"Polling timed out; continue GET for taskId={task_id}.")

raw_outputs = data.get("output")
if not isinstance(raw_outputs, list):
    raise RuntimeError(f"Missing output list; inspect taskId={task_id}.")
outputs = {
    item["type"]: item
    for item in raw_outputs
    if isinstance(item, dict) and item.get("type") in ("video", "caption")
}
if "video" not in outputs:
    raise RuntimeError("Successful task has no video artifact.")
for kind, artifact in outputs.items():
    if not isinstance(artifact.get("url"), str) or not artifact["url"]:
        raise RuntimeError(f"Missing {kind} URL; inspect taskId={task_id}.")
    suffix = payload["input"]["output_format"] if kind == "video" else "srt"
    target = Path(f"avatar-v.{suffix}")
    # Artifact downloads do not need the API Authorization header.
    with requests.get(artifact["url"], stream=True, timeout=(10, 120)) as response:
        response.raise_for_status()
        with target.open("wb") as file:
            for chunk in response.iter_content(chunk_size=1024 * 1024):
                if chunk:
                    file.write(chunk)
    print("saved:", target)

Welche Parameter müssen ausdrücklich gesetzt werden?

Feld	Regel und Standardwert
avatar	Erforderlich, englischer Avatar-Request-Wert
prompt / audio_url	Eines von beiden; Skript max. 5.000 Zeichen, Audio max. 600 Sekunden, max. 32 MiB
voice	Beim Skript-Pfad optional, Standard Warm Pro Narrator
resolution	Standard 720p, optional 1080p, kleingeschrieben 4k
aspect_ratio	Standard 16:9; außerdem 9:16, 4:5, 5:4, 1:1, auto
fit	Standard cover, optional contain
caption	Standard false; true liefert separates SRT
output_format	Standard mp4, optional webm
remove_background	Standard false; für transparente Zwecke true in Kombination mit webm wählen, den gewählten Avatar zuerst mit einem kurzen Clip prüfen
background	Objekt; type ist color oder image, value enthält eine Hex-Farbe oder eine HTTP(S)-Bild-URL

Auflösung und Seitenverhältnis sind zwei Parameter: Für erklärende Querformate 16:9, für vertikale Sprechvideos 9:16, beides in der Anfrage angeben. Prüfen Sie nach dem Download die tatsächlichen Dateimaße. Bei transparentem WebM prüfen Sie zuerst die Freistellung des gewählten Avatars und importieren Sie dann in die Schnittsoftware.

Untertitel werden nicht ins Bild eingebrannt, sondern im Player oder in der Schnittsoftware überlagert. Das folgende vertikale Beispiel setzt caption=true und liefert ein separates SRT; das Video ist 1080×1920, 6.52 Sekunden, die Anfrage war 1080p, 9:16. Die separate SRT-Untertiteldatei kann beim Schnitt importiert werden.

New drop just landed: our travel mug keeps coffee hot for twelve hours. Swipe up and grab yours today!

Mit diesem Prompt generieren → Das Skript ist bereits eingetragen; wählen Sie manuell Riley Casual Front, Charming Charles - Friendly, 9:16 und 1080p, aktivieren Sie Untertitel, Ausgabe MP4.

Welche vier Punkte vor dem Livegang prüfen?

1. Eingaben validieren: Avatar, Steuerungsmodus, englische Request-Werte und Längenlimits.
2. Aufgaben-ID speichern: Bei fehlgeschlagener Abfrage oder Timeout mit derselben ID GET fortsetzen.
3. Alle Artefakte finden: Nach Erfolg anhand type nach video suchen, bei aktivierten Untertiteln nach caption.
4. Download prüfen: Tatsächliche Maße, Ton und Untertiteldatei bestätigen, dann ausliefern.

Wie behandelt man häufige Probleme?

• **Probleme bei der Eingabevalidierung:** Prüfen Sie avatar, das eine der beiden Steuerfelder, englische Request-Werte, Skript- und Audio-Limits; schreiben Sie die Auflösung als 4k, entfernen Sie duration.
• **POST-Timeout:** Prüfen Sie zuerst den Aufgabenrecord; wenn eine taskId vorhanden ist, setzen Sie GET fort, denn jedes POST erstellt eine neue Aufgabe.
• **Aufgabe fail:** Sehen Sie sich die Fehlerursache im Aufgabenrecord an und übermitteln Sie nach Korrektur der entsprechenden Eingaben erneut.
• **Download-Link abgelaufen:** Speichern Sie die Artefakte nach Erfolg rechtzeitig; Untertitel lesen Sie aus type=caption.

Der Server kann auf derselben Ebene wie input "callback": {"url": "https://yourapp.com/webhook", "when": "final"} hinzufügen, das Endzustands-Aufgabenobjekt empfangen und per GET-Abfrage nachholen.

Preisdetails finden Sie in der Sekundenpreis- und Budgettabelle, zum Avatarwechsel siehe zwei Beispiele, die vollständigen Werte in der API-Parameterdokumentation.

Mit diesem Prompt generieren → Das Skript ist bereits eingetragen; wählen Sie manuell Business-Avatar und -Stimme, 1080p, 16:9, MP4, generieren Sie zuerst einen Satz und binden Sie dann das vollständige Skript ein.