OmniHuman v1.5 API: Generazione Programmatica di Video con Avatar

L'esecuzione di OmniHuman v1.5 tramite l'interfaccia Arteza è ottima per creazioni occasionali. Per i flussi di lavoro ad alto volume - outreach di vendita personalizzato, rollout multilingue, generazione video guidata da CMS, digest di notizie automatizzati - vuoi l'API. Questa guida illustra l'autenticazione, gli endpoint, la struttura della richiesta, la gestione dei webhook e i pattern di produzione. Ogni generazione costa gli stessi 960 crediti ($9,60) che tu la richiamai tramite interfaccia o API.

Perché utilizzare l'API

L'API sblocca pattern di automazione che l'interfaccia non può eguagliare:

• Generazione in batch. Esegui 100+ video in una singola esecuzione della pipeline.
• Personalizzazione dinamica. Estrai dati da un CRM e genera un video per ogni prospect.
• Flussi di lavoro programmati. Digest di notizie giornalieri, video di riepilogo settimanali, aggiornamenti attivati.
• Integrazione con stack esistenti. Node.js, Python, Go, Ruby - qualsiasi linguaggio con HTTP può utilizzarlo.
• Produzione riproducibile. Script con controllo versione anziché click manuali dell'interfaccia.

Se il tuo caso d'uso prevede più di 10 video con struttura simile, vale la pena configurare l'API.

Autenticazione

Le richieste all'API di Arteza si autenticano tramite una API key passata nell'header Authorization come token Bearer.

Ottenere la tua API Key

1. Accedi a arteza.ai
2. Naviga alle impostazioni del tuo account
3. Trova la sezione API
4. Genera una nuova API key
5. Conservala in modo sicuro - trattala come una password

Non eseguire mai il commit della tua API key nel controllo del codice sorgente. Usa variabili di ambiente:

export SEEDANCE_API_KEY="your_api_key_here"

Header di autenticazione

Ogni richiesta include:

Authorization: Bearer YOUR_SEEDANCE_API_KEY
Content-Type: application/json

Struttura dell'endpoint

L'API OmniHuman v1.5 segue pattern di generazione asincrona standard:

• POST per creare un job di generazione
• GET per eseguire il polling dello stato e dei risultati
• Webhook per la consegna asincrona (consigliato per la produzione)

URL di base

https://api.arteza.ai/v1

Endpoint chiave

Consulta la documentazione live dell'API Arteza per i percorsi esatti degli endpoint, poiché i percorsi possono evolversi.

Invio di un job di generazione

Struttura della richiesta

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

Riferimento dei parametri

Requisiti dei file di input

Immagine:

• Formati: JPEG, PNG
• Risoluzione: minimo 512x512, 1024x1024+ consigliato
• Accessibile tramite URL HTTPS pubblico

Audio:

• Formati: MP3, WAV, M4A
• Durata: ≤60s per 720p, ≤30s per 1080p
• Accessibile tramite URL HTTPS pubblico

Se i tuoi file non sono già ospitati pubblicamente, caricali su S3, Cloudflare R2, Google Cloud Storage o simili prima di effettuare la chiamata API.

Esempio di richiesta 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']}")

Esempio di richiesta 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}`);

Formato della risposta

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

Il job_id è quello che utilizzi per il polling o per correlare le consegne dei webhook.

Polling dei risultati

Se non stai utilizzando webhook, esegui il polling dell'endpoint dello stato del job fino al completamento.

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

Valori dello stato del job

Utilizzo di webhook (consigliato per la produzione)

I webhook eliminano il polling e ti permettono di creare pipeline guidate da eventi.

Configurazione di un webhook

Passa webhook_url nella tua richiesta di generazione. Seedance POST a quell'URL quando il job si completa.

Payload del webhook

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

Esempio di gestore webhook

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

Sicurezza del webhook

Verifica le firme dei webhook se Arteza fornisce un segreto di firma. Valida sempre che i webhook provengano da Arteza prima di agire su di essi.

Pronto a provare OmniHuman v1.5? Inizia a creare gratuitamente →

Vuoi un presentatore come questo? Prova OmniHuman gratuitamente →

Pattern di produzione

Pattern 1: Pipeline di video di vendita personalizzato

Genera un video per prospect con variabili di script dinamiche.

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)

Consulta guida ai video di vendita per scripting e distribuzione.

Pattern 2: Rollout di contenuti multilingue

Genera lo stesso messaggio in più lingue, stessa 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"]))

Consulta guida multilingue per suggerimenti su voce e traduzione.

Pattern 3: Automazione di digest di notizie giornalieri

Pipeline programmata che recupera i titoli, genera TTS e produce un video giornaliero.

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()

Consulta guida presentatore di notizie.

Pattern 4: Generazione video attivata da CMS

Quando viene pubblicato un nuovo post di blog o prodotto, genera un video complementare.

@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 practice di gestione degli errori

Riprova con backoff esponenziale

Gli errori di rete e i guasti transitori dovrebbero attivare i tentativi, non l'abbandono immediato.

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

Valida gli input prima di inviare

Risparmia crediti convalidando prima di ogni chiamata API:

• L'URL dell'immagine restituisce 200 e content-type image/*
• L'URL audio restituisce 200 e content-type audio/*
• La durata dell'audio è entro il limite per la risoluzione scelta
• Il prompt non è vuoto

Gestire i limiti di velocità

L'API applica i limiti di velocità. Rispetta le risposte 429 e rinuncia appropriatamente.

Monitora il saldo dei crediti

Controlla il saldo dei crediti prima di eseguzioni batch di grandi dimensioni. Rimanere senza crediti a metà batch è evitabile.

Gestione dei costi

Ogni video generato tramite API costa 960 crediti ($9,60). Lo stesso pacchetto di crediti che alimenta l'interfaccia alimenta l'API:

Per i carichi di lavoro API pesanti, il tier Max ti offre il miglior costo effettivo per generazione. Consulta guida ai prezzi per i dettagli.

Stima del costo del progetto

Prima di avviare un'esecuzione batch, calcola il costo totale:

total_cost = number_of_videos * 9.60

Un batch di 1.000 video: $9.600 tariffa base, ~$8.000 su tier Max. Pianifica di conseguenza.

Osservabilità

Per i flussi di lavoro di produzione, traccia queste metriche:

• Tasso di successo - % di job che si completano con successo
• Tempo di generazione medio - per la pianificazione della capacità
• Crediti consumati - totali progressivi per il monitoraggio del budget
• Tasso di consegna webhook - rileva gli errori di consegna dei webhook
• Categorizzazione degli errori - raggruppa i guasti per causa

Registra i job ID insieme ai tuoi ID di correlazione interni per il debug.

Best practice di sicurezza

• Non esporre mai la tua API key lato client. Chiama sempre l'API dal tuo backend.
• Usa variabili di ambiente o un gestore di segreti. Non eseguire mai il commit delle chiavi nel controllo del codice sorgente.
• Ruota le chiavi periodicamente. Trattale come qualsiasi altra credenziale.
• Valida le firme dei webhook quando disponibile.
• Usa HTTPS per tutti gli URL di immagini e audio che passi all'API.
• Limita l'ambito degli endpoint webhook in modo che solo i payload legittimi di Arteza vengano elaborati.

Primi passi con l'API

1. Iscriviti ad Arteza e raccogli i tuoi 50 crediti gratuiti
2. Acquista almeno un pacchetto Starter ($10) per avere abbastanza per una generazione di prova
3. Genera la tua API key nel dashboard
4. Prepara un file di immagine e audio di prova, carica su un URL pubblico
5. Effettua la tua prima chiamata API usando gli esempi di cui sopra
6. Esegui il polling o attendi webhook per recuperare l'URL video
7. Costruisci la tua pipeline di produzione

Per letture correlate, consulta guida completa OmniHuman v1.5, dettaglio dei prezzi, guida ai video di vendita, e guida multilingue.

Pronto a provare OmniHuman v1.5? Inizia a creare gratuitamente →