OmniHuman v1.5 API: Programmatische Avatar-Videogenerierung

OmniHuman v1.5 über die Arteza-Oberfläche zu verwenden, ist ideal für einzelne Erstellungen. Für Workflows mit hohem Volumen, also personalisierte Verkaufsansprachen, mehrsprachige Rollouts, CMS-gesteuerte Videogenerierung oder automatisierte Nachrichten-Digests, empfiehlt sich die API. Diese Anleitung führt durch Authentifizierung, Endpunkte, Anforderungsstruktur, Webhook-Verarbeitung und Produktionsmuster. Jede Generierung kostet 3-72 Credits ($0,30-$7,20), egal ob über die Oberfläche oder die API aufgerufen.

Kurzfassung

• OmniHuman v1.5-Videos programmgesteuert über die Arteza REST API generieren
• Gleiche Preise von $0,30-$7,20 pro Generierung wie in der Oberfläche, kein API-Aufschlag
• Asynchrone Generierung mit Webhook- oder Polling-basiertem Abrufen der Ergebnisse
• Ideal für personalisierte Vertriebsvideos, automatisierte Trainingsbibliotheken und mehrsprachige Rollouts
• Authentifizierung per API-Schlüssel aus dem Arteza-Dashboard

Warum die API nutzen

Die API ermöglicht Automatisierungsmuster, die die Oberfläche nicht bieten kann:

• Stapelgenerierung. Mehr als 100 Videos in einem einzigen Pipeline-Lauf erstellen.
• Dynamische Personalisierung. Daten aus einem CRM abrufen und pro Interessent ein Video generieren.
• Geplante Workflows. Tägliche Nachrichten-Digests, wöchentliche Zusammenfassungsvideos, ausgelöste Aktualisierungen.
• Integration mit bestehenden Stacks. Node.js, Python, Go, Ruby, jede Sprache mit HTTP kann die API aufrufen.
• Reproduzierbare Produktion. Versionskontrollierte Skripte statt manueller Klicks in der Oberfläche.

Wenn der Anwendungsfall mehr als 10 Videos mit ähnlicher Struktur umfasst, lohnt sich die Einrichtung der API.

Authentifizierung

Arteza API-Anfragen authentifizieren sich über einen API-Schlüssel, der im Authorization-Header als Bearer-Token übergeben wird.

API-Schlüssel erhalten

1. Bei arteza.ai anmelden
2. Zu den Kontoeinstellungen navigieren
3. Den API-Bereich aufrufen
4. Einen neuen API-Schlüssel generieren
5. Sicher speichern, wie ein Passwort behandeln

Den API-Schlüssel niemals in die Quellcodeverwaltung übertragen. Umgebungsvariablen verwenden:

export SEEDANCE_API_KEY="your_api_key_here"

Authentifizierungs-Header

Jede Anfrage enthält:

Authorization: Bearer YOUR_SEEDANCE_API_KEY
Content-Type: application/json

Endpunkt-Struktur

Die OmniHuman v1.5 API folgt standardmäßigen asynchronen Generierungsmustern:

• POST, um einen Generierungsjob zu erstellen
• GET, um Status und Ergebnisse abzurufen
• Webhook für asynchrone Zustellung (für die Produktion empfohlen)

Basis-URL

https://api.arteza.ai/v1

Wichtige Endpunkte

Die aktuellen Arteza API-Dokumentationen für genaue Endpunktpfade konsultieren, da sich Pfade ändern können.

Einen Generierungsjob einreichen

Anforderungsstruktur

{
  "model": "omnihuman-v1.5",
  "image_url": "https://example.com/portrait.jpg",
  "audio_url": "https://example.com/speech.mp3",
  "prompt": "Modern corporate office with soft natural lighting, medium close-up framing head and shoulders, professional broadcast style",
  "resolution": "1080p",
  "turbo_mode": false,
  "webhook_url": "https://yourapp.com/webhooks/seedance"
}

Parameterreferenz

Anforderungen an Eingabedateien

Bild:

• Formate: JPEG, PNG
• Auflösung: mindestens 512x512, 1024x1024 oder mehr empfohlen
• Über öffentliche HTTPS-URL zugänglich

Audio:

• Formate: MP3, WAV, M4A
• Dauer: maximal 60 Sekunden für 720p, maximal 30 Sekunden für 1080p
• Über öffentliche HTTPS-URL zugänglich

Falls Dateien noch nicht öffentlich gehostet sind, vor dem API-Aufruf auf S3, Cloudflare R2, Google Cloud Storage oder ähnlichen Diensten hochladen.

Beispielanfrage in Python

import os
import requests

SEEDANCE_API_KEY = os.environ["SEEDANCE_API_KEY"]
BASE_URL = "https://api.arteza.ai/v1"

def create_omnihuman_video(image_url, audio_url, prompt,
                           resolution="1080p", turbo=False):
    headers = {
        "Authorization": f"Bearer {SEEDANCE_API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": "omnihuman-v1.5",
        "image_url": image_url,
        "audio_url": audio_url,
        "prompt": prompt,
        "resolution": resolution,
        "turbo_mode": turbo,
    }
    response = requests.post(
        f"{BASE_URL}/omnihuman/generate",
        json=payload,
        headers=headers,
    )
    response.raise_for_status()
    return response.json()

job = create_omnihuman_video(
    image_url="https://cdn.example.com/ceo.jpg",
    audio_url="https://cdn.example.com/weekly-update.mp3",
    prompt="Corporate office with warm lighting, medium close-up, professional style",
)
print(f"Job eingereicht: {job['job_id']}")

Beispielanfrage in Node.js

import fetch from "node-fetch";

const SEEDANCE_API_KEY = process.env.SEEDANCE_API_KEY;
const BASE_URL = "https://api.arteza.ai/v1";

async function createOmnihumanVideo({
  imageUrl,
  audioUrl,
  prompt,
  resolution = "1080p",
  turbo = false,
}) {
  const response = await fetch(`${BASE_URL}/omnihuman/generate`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${SEEDANCE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "omnihuman-v1.5",
      image_url: imageUrl,
      audio_url: audioUrl,
      prompt,
      resolution,
      turbo_mode: turbo,
    }),
  });

  if (!response.ok) {
    throw new Error(`Arteza API-Fehler: ${response.status}`);
  }
  return response.json();
}

const job = await createOmnihumanVideo({
  imageUrl: "https://cdn.example.com/ceo.jpg",
  audioUrl: "https://cdn.example.com/update.mp3",
  prompt: "Modern office, soft lighting, medium close-up",
});
console.log(`Job eingereicht: ${job.job_id}`);

Antwortformat

{
  "job_id": "job_abc123xyz",
  "status": "queued",
  "created_at": "2026-04-10T14:23:00Z",
  "estimated_credits": 46
}

Die job_id wird für das Polling oder die Korrelation von Webhook-Zustellungen verwendet.

Ergebnisse per Polling abrufen

Ohne Webhooks den Jobstatus-Endpunkt abfragen, bis der Job abgeschlossen ist.

import time

def wait_for_video(job_id, timeout_seconds=600, poll_interval=5):
    headers = {"Authorization": f"Bearer {SEEDANCE_API_KEY}"}
    deadline = time.time() + timeout_seconds

    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers=headers,
        )
        response.raise_for_status()
        data = response.json()
        status = data["status"]

        if status == "completed":
            return data["result"]["video_url"]
        if status == "failed":
            raise Exception(f"Generierung fehlgeschlagen: {data.get('error')}")

        time.sleep(poll_interval)

    raise TimeoutError("Job wurde nicht innerhalb des Zeitlimits abgeschlossen")

video_url = wait_for_video(job["job_id"])
print(f"Video bereit: {video_url}")

Jobstatus-Werte

Webhooks verwenden (für die Produktion empfohlen)

Webhooks eliminieren das Polling und ermöglichen ereignisgesteuerte Pipelines.

Webhook konfigurieren

webhook_url in der Generierungsanfrage übergeben. Seedance sendet einen POST an diese URL, wenn der Job abgeschlossen ist.

Webhook-Payload

{
  "event": "job.completed",
  "job_id": "job_abc123xyz",
  "status": "completed",
  "result": {
    "video_url": "https://cdn.arteza.ai/outputs/video_abc123.mp4",
    "resolution": "1080p",
    "duration_seconds": 28.5
  },
  "credits_used": 46,
  "completed_at": "2026-04-10T14:26:45Z"
}

Webhook-Handler-Beispiel

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/seedance", methods=["POST"])
def seedance_webhook():
    payload = request.get_json()

    if payload.get("event") == "job.completed":
        job_id = payload["job_id"]
        video_url = payload["result"]["video_url"]

        # Eigene Geschäftslogik: Video herunterladen, Nutzer benachrichtigen,
        # nachgelagerte Workflows auslösen usw.
        handle_completed_video(job_id, video_url)

    return jsonify({"received": True}), 200

Webhook-Sicherheit

Webhook-Signaturen verifizieren, wenn Arteza ein Signierungsgeheimnis bereitstellt. Immer prüfen, ob Webhooks tatsächlich von Arteza stammen, bevor darauf reagiert wird.

Bereit, OmniHuman v1.5 auszuprobieren? Kostenlos loslegen →

Einen solchen Präsentator gewünscht? OmniHuman kostenlos testen →

Produktionsmuster

Muster 1: Personalisierte Vertriebsvideo-Pipeline

Pro Interessent ein Video mit dynamischen Skriptvariablen generieren.

def generate_sales_video_for_prospect(prospect):
    script = render_template("sales_template.txt", {
        "first_name": prospect["first_name"],
        "company": prospect["company"],
        "trigger": prospect["trigger_event"],
    })

    audio_url = generate_tts(script)

    job = create_omnihuman_video(
        image_url=YOUR_SDR_PHOTO_URL,
        audio_url=audio_url,
        prompt=STANDARD_SCENE_PROMPT,
        resolution="1080p",
    )
    return job["job_id"]

prospects = load_prospects_from_crm()
for prospect in prospects:
    generate_sales_video_for_prospect(prospect)

Scripting und Distribution finden sich in Leitfaden für Verkaufsvideos.

Muster 2: Mehrsprachiger Inhalts-Rollout

Dieselbe Botschaft in mehreren Sprachen mit demselben Foto generieren.

languages = [
    ("en", "english_audio.mp3"),
    ("es", "spanish_audio.mp3"),
    ("pt", "portuguese_audio.mp3"),
    ("fr", "french_audio.mp3"),
    ("de", "german_audio.mp3"),
]

jobs = []
for lang_code, audio_file in languages:
    audio_url = upload_to_cdn(audio_file)
    job = create_omnihuman_video(
        image_url=SPOKESPERSON_PHOTO_URL,
        audio_url=audio_url,
        prompt=STANDARD_PROMPT,
    )
    jobs.append((lang_code, job["job_id"]))

Tipps zu Stimme und Übersetzung finden sich in Leitfaden für mehrsprachige Inhalte.

Muster 3: Automatisierung des täglichen Nachrichten-Digests

Geplante Pipeline, die Schlagzeilen abruft, TTS generiert und täglich ein Video produziert.

from datetime import datetime

def daily_news_digest():
    headlines = fetch_top_headlines()
    script = format_headlines_as_script(headlines)
    audio_url = generate_tts(script, voice="broadcast_news")

    job = create_omnihuman_video(
        image_url=NEWS_ANCHOR_PHOTO_URL,
        audio_url=audio_url,
        prompt="Professional news studio, broadcast style, medium close-up",
        resolution="720p",
    )
    return job["job_id"]

# Per Cron, Airflow oder einem anderen Workflow-Tool planen
daily_news_digest()

Weitere Informationen finden sich in Leitfaden für Nachrichtensprecher.

Muster 4: CMS-ausgelöste Videogenerierung

Wenn ein neuer Blogbeitrag oder ein neues Produkt veröffentlicht wird, ein Begleitvideo generieren.

@app.route("/cms/published", methods=["POST"])
def on_content_published():
    content = request.get_json()
    script = summarize_content(content["body"])
    audio_url = generate_tts(script)

    job = create_omnihuman_video(
        image_url=BRAND_SPOKESPERSON_PHOTO,
        audio_url=audio_url,
        prompt=BRAND_SCENE_PROMPT,
        webhook_url="https://yourapp.com/webhooks/seedance",
    )
    store_job_mapping(content["id"], job["job_id"])
    return {"ok": True}

Best Practices zur Fehlerbehandlung

Wiederholung mit exponentiellem Backoff

Netzwerkfehler und vorübergehende Ausfälle sollten Wiederholungsversuche auslösen, keine sofortige Aufgabe.

import time

def create_with_retry(params, max_retries=3):
    delay = 2
    for attempt in range(max_retries):
        try:
            return create_omnihuman_video(**params)
        except requests.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(delay)
            delay *= 2

Eingaben vor dem Einreichen validieren

Credits sparen, indem vor jedem API-Aufruf validiert wird:

• Bild-URL gibt 200 zurück und hat Content-Type image/*
• Audio-URL gibt 200 zurück und hat Content-Type audio/*
• Audiodauer liegt innerhalb des Limits für die gewählte Auflösung
• Prompt ist nicht leer

Rate-Limits beachten

Die API setzt Rate-Limits durch. 429-Antworten respektieren und angemessen zurückgehen.

Guthaben-Saldo überwachen

Den Guthaben-Saldo vor großen Stapelläufen prüfen. Das Aufbrauchen von Credits mitten in einem Stapel lässt sich vermeiden.

Kostenverwaltung

Ein über die API generiertes Video kostet 2,4 Credits pro Audiosekunde, also 72 Credits (7,20 Dollar) für 30 Sekunden. Dieselben Credits, die die Oberfläche antreiben, treiben auch die API an:

Bei intensiver API-Nutzung bietet der Studio-Tarif die besten effektiven Kosten pro Generierung. Details finden sich in Leitfaden zu den Preisen.

Projektkosten schätzen

Vor einem Stapellauf die Gesamtkosten berechnen:

total_cost = number_of_videos * 4.60

Ein Stapellauf mit 1.000 Videos à 30 Sekunden: 7.200 Dollar zum Basistarif, und deutlich weniger mit einem Monatstarif. Entsprechend budgetieren.

Observability

Für Produktions-Workflows diese Metriken verfolgen:

• Erfolgsrate - Prozentsatz der Jobs, die erfolgreich abgeschlossen werden
• Durchschnittliche Generierungszeit - für die Kapazitätsplanung
• Verbrauchte Credits - laufende Summen für das Budget-Tracking
• Webhook-Zustellrate - Webhook-Zustellungsfehler erkennen
• Fehlerkategorisierung - Fehlschläge nach Ursache gruppieren

Job-IDs zusammen mit internen Korrelations-IDs für das Debugging protokollieren.

Sicherheits-Best-Practices

• API-Schlüssel niemals clientseitig offenlegen. Die API immer vom Backend aus aufrufen.
• Umgebungsvariablen oder einen Secrets-Manager verwenden. Schlüssel niemals in die Quellcodeverwaltung übertragen.
• Schlüssel regelmäßig rotieren. Wie jede andere Zugangsdaten behandeln.
• Webhook-Signaturen validieren, wenn verfügbar.
• HTTPS für alle Bild- und Audio-URLs verwenden, die an die API übergeben werden.
• Webhook-Endpunkte abgrenzen, damit nur legitime Arteza-Payloads verarbeitet werden.

Erste Schritte mit der API

1. Bei Arteza anmelden und 10 Gratis-Credits einsammeln
2. Mindestens den Starter-Tarif ($5/Monat) abonnieren, um ausreichend Credits für eine Testgenerierung zu haben
3. API-Schlüssel im Dashboard generieren
4. Testbild und Audiodatei vorbereiten und auf eine öffentliche URL hochladen
5. Ersten API-Aufruf mit den obigen Beispielen durchführen
6. Per Polling warten oder auf Webhook warten, um die Video-URL abzurufen
7. Produktions-Pipeline aufbauen

Weiterführende Lektüre: vollständiger OmniHuman v1.5-Leitfaden, Preisübersicht, Leitfaden für Verkaufsvideos und Leitfaden für mehrsprachige Inhalte.

Bereit, OmniHuman v1.5 auszuprobieren? Kostenlos loslegen →