OmniHuman v1.5 API: Programmatische Avatar-Videogenerierung

Die Ausführung von OmniHuman v1.5 über die Arteza-Benutzeroberfläche ist großartig für einmalige Erstellungen. Für hochvolumige Arbeitsabläufe - personalisierte Sales-Outreach, mehrsprachige Rollouts, CMS-gesteuerte Videogenerierung, automatisierte Nachrichten-Digests - möchten Sie die API. Dieses Handbuch führt Sie durch Authentifizierung, Endpunkte, Anforderungsstruktur, Webhook-Verarbeitung und Produktionsmuster. Jede Generierung kostet gleich 960 Credits (9,60 Dollar), egal ob Sie sie über die Benutzeroberfläche oder die API aufrufen.

Warum die API verwenden

Die API ermöglicht Automatisierungsmuster, die die Benutzeroberfläche nicht erfüllen kann:

• Batch-Generierung. Führen Sie 100+ Videos in einer einzigen Pipeline-Ausführung aus.
• Dynamische Personalisierung. Daten aus einem CRM abrufen und ein Video pro Interessent generieren.
• Geplante Arbeitsabläufe. Tägliche Nachrichten-Digests, wöchentliche Zusammenfassungsvideos, ausgelöste Updates.
• Integration mit bestehenden Stacks. Node.js, Python, Go, Ruby - jede Sprache mit HTTP kann es aufrufen.
• Reproduzierbare Produktion. Versionskontrollierte Skripte statt manueller Klicks in der Benutzeroberfläche.

Wenn Ihr 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 Header Authorization als Bearer-Token übergeben wird.

API-Schlüssel abrufen

1. Melden Sie sich unter arteza.ai an
2. Navigieren Sie zu Ihren Kontoeinstellungen
3. Suchen Sie den API-Bereich
4. Generieren Sie einen neuen API-Schlüssel
5. Speichern Sie ihn sicher - behandeln Sie ihn wie ein Passwort

Übergeben Sie Ihren API-Schlüssel niemals an die Quellkontrolle. Verwenden Sie Umgebungsvariablen:

export SEEDANCE_API_KEY="your_api_key_here"

Authentifizierungs-Header

Jede Anfrage beinhaltet:

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 den Status und die Ergebnisse zu polling
• Webhook für asynchrone Bereitstellung (empfohlen für Produktion)

Basis-URL

https://api.arteza.ai/v1

Wichtige Endpunkte

Konsultieren Sie die Live-Arteza API-Dokumentation für genaue Endpunkt-Pfade, da sich Pfade ändern können.

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"
}

Parameter-Referenz

Anforderungen an Eingabedateien

Bild:

• Formate: JPEG, PNG
• Auflösung: Mindestens 512x512, 1024x1024+ empfohlen
• Zugänglich über öffentliche HTTPS-URL

Audio:

• Formate: MP3, WAV, M4A
• Dauer: ≤60s für 720p, ≤30s für 1080p
• Zugänglich über öffentliche HTTPS-URL

Wenn Ihre Dateien nicht bereits öffentlich gehostet sind, laden Sie sie vor dem API-Aufruf in S3, Cloudflare R2, Google Cloud Storage oder ähnliches hoch.

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 submitted: {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 error: ${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 submitted: ${job.job_id}`);

Antwortformat

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

Die job_id ist das, was Sie zum Polling oder zur Korrelation von Webhook-Lieferungen verwenden.

Polling für Ergebnisse

Wenn Sie keine Webhooks verwenden, polling Sie den Job-Status-Endpunkt bis zum Jobabschluss.

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"Generation failed: {data.get('error')}")

        time.sleep(poll_interval)

    raise TimeoutError("Job did not complete within timeout")

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

Job-Statuswerte

Webhooks verwenden (empfohlen für Produktion)

Webhooks eliminieren Polling und ermöglichen Ihnen, ereignisgesteuerte Pipelines zu erstellen.

Webhook konfigurieren

Übergeben Sie webhook_url in Ihrer Generierungsanfrage. Seedance POSTs 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": 960,
  "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"]

        # Your business logic: download video, notify users,
        # trigger downstream workflows, etc.
        handle_completed_video(job_id, video_url)

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

Webhook-Sicherheit

Überprüfen Sie Webhook-Signaturen, falls Arteza einen Signaturgeheimnis bereitstellt. Überprüfen Sie immer, dass Webhooks von Arteza kommen, bevor Sie darauf reagieren.

Bereit, OmniHuman v1.5 auszuprobieren? Kostenlos erstellen →

Möchten Sie einen Presenter wie diesen? OmniHuman kostenlos testen →

Produktionsmuster

Muster 1: Personalisierte Sales-Video-Pipeline

Generieren Sie ein Video pro Interessent mit dynamischen Skriptvariablen.

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)

Siehe Verkaufsvideos-Anleitung für Skripterstellung und Verteilung.

Muster 2: Mehrsprachiger Content-Rollout

Generieren Sie dieselbe Nachricht in mehreren Sprachen, gleiches Foto.

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"]))

Siehe Mehrsprachige Anleitung für Sprach- und Übersetzungstipps.

Muster 3: Automatisierung für tägliches Nachrichten-Digest

Geplante Pipeline, die Schlagzeilen abruft, TTS generiert und ein tägliches 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"]

# Schedule via cron, Airflow, or your workflow tool
daily_news_digest()

Siehe Nachrichtenanker-Anleitung.

Muster 4: CMS-ausgelöste Videogenerierung

Wenn ein neuer Blogbeitrag oder Produkt veröffentlicht wird, generieren Sie ein begleitendes Video.

@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 für Fehlerbehandlung

Wiederholen mit exponentieller Backoff

Netzwerkfehler und vorübergehende Ausfälle sollten Wiederholungen auslösen, nicht 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 überprüfen

Sparen Sie Credits durch Validierung vor jedem API-Aufruf:

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

Ratenlimits handhaben

Die API setzt Ratenlimits durch. Respektieren Sie 429-Antworten und sichern Sie angemessen ab.

Kreditsaldo überwachen

Überprüfen Sie Ihren Kreditsaldo vor großen Batch-Durchläufen. Das Erschöpfen von Credits mitten in einem Batch ist vermeidbar.

Kostenverwaltung

Jedes API-generierte Video kostet 960 Credits (9,60 Dollar). Dasselbe Kreditpaket, das die Benutzeroberfläche antreibt, treibt die API an:

Für schwere API-Workloads bietet die Max-Stufe die besten effektiven Kosten pro Generierung. Siehe Preisübersicht für Details.

Projektkosten schätzen

Bevor Sie einen Batch-Durchlauf starten, berechnen Sie die Gesamtkosten:

total_cost = number_of_videos * 9.60

Ein 1.000-Video-Batch: 9.600 Dollar Basisrate, ~8.000 Dollar auf Max-Stufe. Budgetieren Sie entsprechend.

Observability

Für Produktions-Arbeitsabläufe verfolgen Sie diese Metriken:

• Erfolgsquote - % der Jobs, die erfolgreich abgeschlossen werden
• Durchschnittliche Generierungszeit - für Kapazitätsplanung
• Verbrauchte Credits - laufende Summen für Budget-Tracking
• Webhook-Lieferungsrate - Fehler bei Webhook-Lieferung erkennen
• Fehler-Kategorisierung - Fehler nach Ursache gruppieren

Protokollieren Sie Job-IDs zusammen mit Ihren internen Korrelations-IDs zum Debuggen.

Best Practices für Sicherheit

• Geben Sie Ihren API-Schlüssel niemals client-seitig preis. Rufen Sie die API immer von Ihrem Backend aus auf.
• Verwenden Sie Umgebungsvariablen oder einen Geheimnisse-Manager. Übergeben Sie niemals Schlüssel an die Quellkontrolle.
• Rotieren Sie Schlüssel regelmäßig. Behandeln Sie sie wie alle anderen Anmeldedaten.
• Überprüfen Sie Webhook-Signaturen, wenn verfügbar.
• Verwenden Sie HTTPS für alle Bild- und Audio-URLs, die Sie an die API übergeben.
• Beschränken Sie Webhook-Endpunkte, damit nur legitime Arteza-Payloads verarbeitet werden.

Erste Schritte mit der API

1. Bei Arteza anmelden und sammeln Sie Ihre 50 kostenlosen Credits
2. Kaufen Sie mindestens ein Starter-Paket (10 Dollar), um genug für eine Test-Generierung zu haben
3. Generieren Sie Ihren API-Schlüssel im Dashboard
4. Bereiten Sie ein Test-Bild und eine Audio-Datei vor, laden Sie sie zu einer öffentlichen URL hoch
5. Machen Sie Ihren ersten API-Aufruf anhand der obigen Beispiele
6. Polling oder warten auf Webhook zum Abrufen der Video-URL
7. Bauen Sie Ihre Produktions-Pipeline auf

Für weitere Informationen siehe Vollständige OmniHuman v1.5-Anleitung, Preisaufschlüsselung, Verkaufsvideos-Anleitung und Mehrsprachige Anleitung.

Bereit, OmniHuman v1.5 auszuprobieren? Kostenlos erstellen →