API OmniHuman v1.5: Geração Programática de Vídeos de Avatar

Executar OmniHuman v1.5 através da interface do Arteza é ótimo para criações pontuais. Para fluxos de trabalho em alto volume - alcance de vendas personalizado, lançamentos multilíngues, geração de vídeo orientada por CMS, resumos de notícias automatizados - você quer a API. Este guia percorre autenticação, endpoints, estrutura de solicitação, manipulação de webhook e padrões de produção. Cada geração custa o mesmo 960 créditos ($9,60) seja invocado via interface ou API.

Por que usar a API

A API desbloqueia padrões de automação que a interface não consegue corresponder:

• Geração em lote. Execute 100+ vídeos em uma única execução de pipeline.
• Personalização dinâmica. Puxe dados de um CRM e gere um vídeo por prospect.
• Fluxos de trabalho agendados. Resumos diários de notícias, vídeos de resumo semanais, atualizações acionadas.
• Integração com pilhas existentes. Node.js, Python, Go, Ruby - qualquer linguagem com HTTP pode chamá-la.
• Produção reproduzível. Scripts versionados em controle de versão em vez de cliques manuais na interface.

Se seu caso de uso envolver mais de 10 vídeos com estrutura similar, a API vale a pena configurar.

Autenticação

As solicitações da API do Arteza se autenticam via uma chave de API passada no cabeçalho Authorization como um token Bearer.

Obtendo sua chave de API

1. Faça login em arteza.ai
2. Navegue até as configurações da sua conta
3. Encontre a seção API
4. Gere uma nova chave de API
5. Armazene-a com segurança - trate-a como uma senha

Nunca faça commit de sua chave de API no controle de versão. Use variáveis de ambiente:

export SEEDANCE_API_KEY="sua_chave_api_aqui"

Cabeçalho de Autenticação

Cada solicitação inclui:

Authorization: Bearer SUA_SEEDANCE_API_KEY
Content-Type: application/json

Estrutura do Endpoint

A API OmniHuman v1.5 segue padrões de geração assíncrona padrão:

• POST para criar um trabalho de geração
• GET para fazer polling de status e resultados
• Webhook para entrega assíncrona (recomendado para produção)

URL Base

https://api.arteza.ai/v1

Endpoints-chave

Consulte a documentação da API do Arteza ao vivo para caminhos de endpoint exatos, pois os caminhos podem evoluir.

Enviando um Trabalho de Geração

Estrutura da Solicitação

{
  "model": "omnihuman-v1.5",
  "image_url": "https://example.com/portrait.jpg",
  "audio_url": "https://example.com/speech.mp3",
  "prompt": "Escritório corporativo moderno com iluminação natural suave, enquadramento de close médio cabeça e ombros, estilo broadcast profissional",
  "resolution": "1080p",
  "turbo_mode": false,
  "webhook_url": "https://yourapp.com/webhooks/seedance"
}

Referência de Parâmetro

Requisitos de Arquivo de Entrada

Imagem:

• Formatos: JPEG, PNG
• Resolução: mínimo 512x512, 1024x1024+ recomendado
• Acessível via URL HTTPS pública

Áudio:

• Formatos: MP3, WAV, M4A
• Duração: ≤60s para 720p, ≤30s para 1080p
• Acessível via URL HTTPS pública

Se seus arquivos não estiverem já hospedados publicamente, carregue-os para S3, Cloudflare R2, Google Cloud Storage ou similar antes de fazer a chamada da API.

Solicitação de Exemplo em 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="Escritório corporativo com iluminação quente, close médio, estilo profissional",
)
print(f"Trabalho enviado: {job['job_id']}")

Solicitação de Exemplo em 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(`Erro na API Arteza: ${response.status}`);
  }
  return response.json();
}

const job = await createOmnihumanVideo({
  imageUrl: "https://cdn.example.com/ceo.jpg",
  audioUrl: "https://cdn.example.com/update.mp3",
  prompt: "Escritório moderno, iluminação suave, close médio",
});
console.log(`Trabalho enviado: ${job.job_id}`);

Formato de Resposta

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

O job_id é o que você usa para polling ou correlacionando entregas de webhook.

Fazendo Polling de Resultados

Se você não está usando webhooks, faça polling do endpoint de status do trabalho até que o trabalho seja concluído.

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"Falha na geração: {data.get('error')}")

        time.sleep(poll_interval)

    raise TimeoutError("Trabalho não foi concluído dentro do tempo limite")

video_url = wait_for_video(job["job_id"])
print(f"Vídeo pronto: {video_url}")

Valores de Status do Trabalho

Usando Webhooks (Recomendado para Produção)

Webhooks eliminam polling e permite construir pipelines orientadas por eventos.

Configurando um Webhook

Passe webhook_url em sua solicitação de geração. Seedance faz POST para essa URL quando o trabalho é concluído.

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

Exemplo de Manipulador de 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"]

        # Sua lógica de negócios: baixar vídeo, notificar usuários,
        # acionar fluxos de trabalho posteriores, etc.
        handle_completed_video(job_id, video_url)

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

Segurança de Webhook

Verifique assinaturas de webhook se o Arteza fornecer um segredo de assinatura. Sempre valide que webhooks vêm do Arteza antes de agir sobre eles.

Pronto para experimentar OmniHuman v1.5? Comece a criar gratuitamente →

Quer um apresentador assim? Experimente OmniHuman gratuitamente →

Padrões de Produção

Padrão 1: Pipeline de Vídeo de Vendas Personalizado

Gere um vídeo por prospect com variáveis de script dinâmicas.

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)

Veja o guia de vídeos de vendas para scripting e distribuição.

Padrão 2: Lançamento de Conteúdo Multilíngue

Gere a mesma mensagem em vários idiomas, mesma 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"]))

Veja o guia multilíngue para dicas de voz e tradução.

Padrão 3: Automação de Resumo de Notícias Diárias

Pipeline agendado que puxa manchetes, gera TTS e produz um vídeo diário.

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="Estúdio profissional de notícias, estilo broadcast, close médio",
        resolution="720p",
    )
    return job["job_id"]

# Agende via cron, Airflow ou sua ferramenta de fluxo de trabalho
daily_news_digest()

Veja o guia de âncora de notícias.

Padrão 4: Geração de Vídeo Acionada por CMS

Quando uma nova postagem de blog ou produto é publicado, gere um vídeo complementar.

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

Melhores Práticas de Manipulação de Erros

Tentar Novamente com Backoff Exponencial

Erros de rede e falhas transitórias devem acionar novas tentativas, não abandono imediato.

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

Validar Entradas Antes de Enviar

Economize créditos validando antes de cada chamada de API:

• URL de imagem retorna 200 e content-type image/*
• URL de áudio retorna 200 e content-type audio/*
• Duração de áudio está dentro do limite para a resolução escolhida
• Prompt não está vazio

Manipular Limites de Taxa

A API impõe limites de taxa. Respeite respostas 429 e recue apropriadamente.

Monitorar Saldo de Crédito

Verifique seu saldo de crédito antes de execuções em lote grandes. Ficar sem créditos no meio de um lote é evitável.

Gestão de Custos

Cada vídeo gerado por API custa 960 créditos ($9,60). O mesmo pacote de crédito que alimenta a interface alimenta a API:

Para cargas de trabalho de API pesadas, o nível Max oferece o melhor custo efetivo por geração. Veja o guia de preços para detalhes.

Estimando Custo do Projeto

Antes de iniciar uma execução em lote, calcule o custo total:

total_cost = number_of_videos * 9.60

Um lote de 1.000 vídeos: $9.600 taxa base, ~$8.000 no nível Max. Orce adequadamente.

Observabilidade

Para fluxos de trabalho de produção, rastreie estas métricas:

• Taxa de sucesso - % de trabalhos que são concluídos com sucesso
• Tempo médio de geração - para planejamento de capacidade
• Créditos consumidos - totalizações contínuas para rastreamento de orçamento
• Taxa de entrega de webhook - detectar falhas de entrega de webhook
• Categorização de erro - agrupar falhas por causa

Registre IDs de trabalho junto com seus IDs de correlação internos para depuração.

Melhores Práticas de Segurança

• Nunca exponha sua chave de API no lado do cliente. Sempre chame a API do seu backend.
• Use variáveis de ambiente ou um gerenciador de segredos. Nunca faça commit de chaves no controle de versão.
• Gire as chaves periodicamente. Trate-as como qualquer outra credencial.
• Valide assinaturas de webhook quando disponível.
• Use HTTPS para todas as URLs de imagem e áudio que você passa para a API.
• Escope endpoints de webhook para que apenas payloads legítimos do Arteza sejam processados.

Começando com a API

1. Inscreva-se no Arteza e colete seus 50 créditos grátis
2. Compre pelo menos um pacote Starter ($10) para ter créditos suficientes para uma geração de teste
3. Gere sua chave de API no painel
4. Prepare um arquivo de imagem e áudio de teste, carregue para uma URL pública
5. Faça sua primeira chamada de API usando os exemplos acima
6. Faça polling ou espere webhook para recuperar a URL do vídeo
7. Construa seu pipeline de produção

Para leitura relacionada, veja o guia completo do OmniHuman v1.5, detalhamento de preços, guia de vídeos de vendas, e guia multilíngue.

Pronto para experimentar OmniHuman v1.5? Comece a criar gratuitamente →