OmniHuman v1.5 API: programowe generowanie wideo z awatarami

Korzystanie z OmniHuman v1.5 przez interfejs Arteza sprawdza się świetnie przy jednorazowym tworzeniu treści. W przypadku przepływów pracy o dużym wolumenie, takich jak spersonalizowane kampanie sprzedażowe, wdrożenia wielojęzyczne, generowanie wideo sterowane przez CMS czy automatyczne podsumowania newsów, warto sięgnąć po API. Ten przewodnik omawia uwierzytelnianie, punkty końcowe, strukturę żądań, obsługę webhooków i wzorce produkcyjne. Każde generowanie kosztuje tyle samo 3-72 kredytów ($0,30-$7,20) niezależnie od tego, czy wywołujesz je przez interfejs, czy przez API.

Dlaczego warto używać API

API otwiera możliwości automatyzacji, których interfejs użytkownika nie jest w stanie zapewnić:

• Generowanie wsadowe. Uruchamiaj 100 i więcej filmów w jednym przebiegu potoku.
• Dynamiczna personalizacja. Pobieraj dane z CRM i generuj osobny film dla każdego prospekta.
• Zaplanowane przepływy pracy. Codzienne podsumowania newsów, cotygodniowe filmy podsumowujące, aktualizacje wyzwalane zdarzeniami.
• Integracja z istniejącymi stosami. Node.js, Python, Go, Ruby, każdy język obsługujący HTTP może wywołać API.
• Odtwarzalna produkcja. Skrypty kontrolowane wersją zamiast ręcznych kliknięć w interfejsie.

Jeśli Twój przypadek użycia obejmuje więcej niż 10 filmów o podobnej strukturze, warto skonfigurować API.

Uwierzytelnianie

Żądania do Arteza API są uwierzytelniane za pomocą klucza API przekazywanego w nagłówku Authorization jako token Bearer.

Pobieranie klucza API

1. Zaloguj się na arteza.ai
2. Przejdź do ustawień konta
3. Znajdź sekcję API
4. Wygeneruj nowy klucz API
5. Przechowuj go bezpiecznie, traktuj jak hasło

Nigdy nie umieszczaj klucza API w kontroli wersji. Używaj zmiennych środowiskowych:

export SEEDANCE_API_KEY="your_api_key_here"

Nagłówek uwierzytelniania

Każde żądanie zawiera:

Authorization: Bearer YOUR_SEEDANCE_API_KEY
Content-Type: application/json

Struktura punktów końcowych

API OmniHuman v1.5 stosuje standardowe wzorce asynchronicznego generowania:

• POST do tworzenia zadania generowania
• GET do sprawdzania statusu i wyników
• Webhook do asynchronicznego dostarczania wyników (zalecane w środowisku produkcyjnym)

Bazowy URL

https://api.arteza.ai/v1

Kluczowe punkty końcowe

Sprawdź aktualną dokumentację Arteza API w celu uzyskania dokładnych ścieżek punktów końcowych, ponieważ mogą one ulegać zmianie.

Wysyłanie zadania generowania

Struktura żądania

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

Opis parametrów

Wymagania dotyczące plików wejściowych

Obraz:

• Formaty: JPEG, PNG
• Rozdzielczość: minimum 512x512, zalecane 1024x1024 lub więcej
• Dostępny przez publiczny URL HTTPS

Audio:

• Formaty: MP3, WAV, M4A
• Czas trwania: do 60 s dla 720p, do 30 s dla 1080p
• Dostępny przez publiczny URL HTTPS

Jeśli Twoje pliki nie są jeszcze publicznie hostowane, przed wywołaniem API prześlij je na S3, Cloudflare R2, Google Cloud Storage lub podobną usługę.

Przykładowe żądanie w Pythonie

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"Zadanie wysłane: {job['job_id']}")

Przykładowe żądanie w 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(`Zadanie wysłane: ${job.job_id}`);

Format odpowiedzi

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

Wartość job_id służy do pollingu lub korelowania dostaw webhooków.

Sprawdzanie wyników przez polling

Jeśli nie korzystasz z webhooków, odpytuj punkt końcowy statusu zadania, dopóki zadanie nie zostanie ukończone.

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"Generowanie nie powiodło się: {data.get('error')}")

        time.sleep(poll_interval)

    raise TimeoutError("Zadanie nie zostało ukończone w wyznaczonym czasie")

video_url = wait_for_video(job["job_id"])
print(f"Film gotowy: {video_url}")

Wartości statusu zadania

Używanie webhooków (zalecane w środowisku produkcyjnym)

Webhooki eliminują polling i pozwalają budować potoki sterowane zdarzeniami.

Konfigurowanie webhooka

Przekaż webhook_url w żądaniu generowania. Seedance wysyła żądanie POST na ten URL po zakończeniu zadania.

Ładunek webhooka

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

Przykładowy handler webhooka

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

        # Twoja logika biznesowa: pobierz film, powiadom użytkowników,
        # wyzwól dalsze przepływy pracy itp.
        handle_completed_video(job_id, video_url)

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

Bezpieczeństwo webhooków

Weryfikuj sygnatury webhooków, jeśli Arteza udostępnia tajny klucz podpisywania. Zawsze sprawdzaj, czy webhooki pochodzą od Arteza, zanim podejmiesz na ich podstawie działanie.

Gotowy, żeby wypróbować OmniHuman v1.5? Zacznij tworzyć za darmo →

Chcesz mieć prezentera jak na tym filmie? Wypróbuj OmniHuman za darmo →

Wzorce produkcyjne

Wzorzec 1: Spersonalizowany potok filmów sprzedażowych

Generuj jeden film dla każdego prospekta z dynamicznymi zmiennymi skryptu.

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)

Zobacz przewodnik po filmach sprzedażowych, gdzie znajdziesz wskazówki dotyczące tworzenia skryptów i dystrybucji.

Wzorzec 2: Wielojęzyczne wdrożenie treści

Generuj tę samą wiadomość w wielu językach, korzystając z tego samego zdjęcia.

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

Zobacz przewodnik po wielu językach, gdzie znajdziesz wskazówki dotyczące głosu i tłumaczenia.

Wzorzec 3: Automatyzacja codziennych podsumowań newsów

Zaplanowany potok, który pobiera nagłówki, generuje TTS i produkuje codzienny film.

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

# Zaplanuj przez cron, Airflow lub swoje narzędzie do przepływów pracy
daily_news_digest()

Zobacz przewodnik po prezenterach wiadomości.

Wzorzec 4: Generowanie wideo wyzwalane przez CMS

Gdy nowy wpis na blogu lub produkt zostanie opublikowany, automatycznie generuj towarzyszący film.

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

Najlepsze praktyki obsługi błędów

Ponawianie prób z wykładniczym opóźnieniem

Błędy sieciowe i przejściowe awarie powinny wyzwalać ponowne próby, a nie natychmiastowe porzucenie zadania.

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

Walidacja danych wejściowych przed wysłaniem

Oszczędzaj kredyty, weryfikując dane przed każdym wywołaniem API:

• URL obrazu zwraca 200 i content-type image/*
• URL audio zwraca 200 i content-type audio/*
• Czas trwania audio mieści się w limicie dla wybranej rozdzielczości
• Prompt nie jest pusty

Obsługa limitów żądań

API wymusza limity żądań. Respektuj odpowiedzi 429 i odpowiednio zwalniaj tempo wysyłania.

Monitorowanie salda kredytów

Sprawdzaj saldo kredytów przed dużymi uruchomieniami wsadowymi. Wyczerpanie kredytów w połowie partii jest do uniknięcia.

Zarządzanie kosztami

Wideo wygenerowane przez API kosztuje 2,4 kredytu za sekundę audio, czyli 72 kredyty ($7,20) za 30 sekund. Te same kredyty, które napędzają interfejs, napędzają API:

Przy intensywnym wykorzystaniu API plan Studio zapewnia najniższy efektywny koszt na generowanie. Zobacz przewodnik po cenach, aby poznać szczegóły.

Szacowanie kosztów projektu

Przed uruchomieniem partii oblicz łączny koszt:

total_cost = number_of_videos * 4.60

Partia 1000 filmów 30-sekundowych to $7 200 według stawki podstawowej, a znacznie mniej w ramach planu miesięcznego. Zaplanuj budżet odpowiednio.

Obserwowalność

W przepływach pracy produkcyjnych śledź następujące metryki:

• Wskaźnik sukcesu - procent zadań kończonych pomyślnie
• Średni czas generowania - na potrzeby planowania pojemności
• Zużyte kredyty - sumy kroczące do śledzenia budżetu
• Wskaźnik dostarczania webhooków - wykrywaj błędy w dostarczaniu webhooków
• Kategoryzacja błędów - grupuj awarie według przyczyn

Rejestruj identyfikatory zadań razem z wewnętrznymi identyfikatorami korelacji w celach debugowania.

Najlepsze praktyki bezpieczeństwa

• Nigdy nie ujawniaj klucza API po stronie klienta. Zawsze wywołuj API z backendu.
• Używaj zmiennych środowiskowych lub menedżera sekretów. Nigdy nie umieszczaj kluczy w kontroli wersji.
• Regularnie rotuj klucze. Traktuj je jak każde inne poświadczenie.
• Weryfikuj sygnatury webhooków, gdy są dostępne.
• Używaj HTTPS dla wszystkich URL-i obrazów i audio przekazywanych do API.
• Ogranicz zakres punktów końcowych webhooków, aby przetwarzały tylko prawidłowe ładunki od Arteza.

Pierwsze kroki z API

1. Zarejestruj się w Arteza i odbierz 10 darmowych kredytów
2. Wykup co najmniej plan Starter ($5 miesięcznie), aby mieć wystarczającą ilość kredytów na testowe generowanie
3. Wygeneruj klucz API w panelu
4. Przygotuj testowy obraz i plik audio, prześlij je pod publiczny URL
5. Wykonaj pierwsze wywołanie API, korzystając z powyższych przykładów
6. Użyj pollingu lub poczekaj na webhook, aby pobrać URL wideo
7. Zbuduj swój potok produkcyjny

Powiązane materiały znajdziesz w kompletny przewodnik po OmniHuman v1.5, zestawienie cen, przewodnik po filmach sprzedażowych oraz przewodnik po wielu językach.

Gotowy, żeby wypróbować OmniHuman v1.5? Zacznij tworzyć za darmo →