API do OmniHuman v1.5: geração programática de vídeos com avatares

Usar o OmniHuman v1.5 pela interface do Arteza é ótimo para criações avulsas. Para fluxos de trabalho de alto volume, como abordagens de vendas personalizadas, lançamentos multilíngues, geração de vídeo orientada por CMS e resumos de notícias automatizados, a API é a melhor opção. Este guia percorre autenticação, endpoints, estrutura de requisição, tratamento de webhooks e padrões de produção. Cada geração custa os mesmos 3-72 créditos ($0,30-$7,20) independentemente de ser feita pela interface ou pela API.

Resumo rápido

• Gere vídeos do OmniHuman v1.5 programaticamente via API REST do Arteza
• O mesmo preço de $0,30-$7,20 por geração da interface, sem acréscimo para uso da API
• Geração assíncrona com recuperação de resultados via webhook ou polling
• Ideal para vídeos de vendas personalizados, bibliotecas de treinamento automatizadas e lançamentos multilíngues
• Autenticação via chave de API do painel do Arteza

Por que usar a API

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

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

Se o seu caso de uso envolve mais de 10 vídeos com estrutura semelhante, vale a pena configurar a API.

Autenticação

As requisições à API do Arteza são autenticadas por meio de uma chave de API passada no cabeçalho Authorization como token Bearer.

Obtendo sua chave de API

1. Faça login em arteza.ai
2. Acesse as configurações da sua conta
3. Localize a seção de API
4. Gere uma nova chave de API
5. Armazene-a com segurança, tratando-a como uma senha

Nunca envie sua chave de API para controle de versão. Use variáveis de ambiente:

export SEEDANCE_API_KEY="your_api_key_here"

Cabeçalho de autenticação

Toda requisição inclui:

Authorization: Bearer YOUR_SEEDANCE_API_KEY
Content-Type: application/json

Estrutura de endpoints

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

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

URL base

https://api.arteza.ai/v1

Principais endpoints

Consulte a documentação da API do Arteza para os caminhos exatos dos endpoints, pois eles podem evoluir.

Enviando um job de geração

Estrutura da requisição

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

Referência de parâmetros

Requisitos dos arquivos de entrada

Imagem:

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

Áudio:

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

Se seus arquivos ainda não estiverem hospedados publicamente, faça upload deles para S3, Cloudflare R2, Google Cloud Storage ou similar antes de fazer a chamada à API.

Exemplo de requisição 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="Corporate office with warm lighting, medium close-up, professional style",
)
print(f"Job enviado: {job['job_id']}")

Exemplo de requisição 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(`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 enviado: ${job.job_id}`);

Formato da resposta

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

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

Verificando resultados por polling

Se você não estiver usando webhooks, verifique o endpoint de status do job periodicamente até que ele 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"Geração falhou: {data.get('error')}")

        time.sleep(poll_interval)

    raise TimeoutError("O job 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 job

Usando webhooks (recomendado para produção)

Os webhooks eliminam o polling e permitem criar pipelines orientados a eventos.

Configurando um webhook

Passe webhook_url na sua requisição de geração. O Seedance faz um POST para essa URL quando o job for concluído.

Payload do 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": 46,
  "completed_at": "2026-04-10T14:26:45Z"
}

Exemplo de handler 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ócio: baixar o vídeo, notificar usuários,
        # acionar fluxos de trabalho subsequentes, etc.
        handle_completed_video(job_id, video_url)

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

Segurança do webhook

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

Pronto para experimentar o OmniHuman v1.5? Comece a criar grátis →

Quer um apresentador assim? Experimente o OmniHuman grátis →

Padrões de produção

Padrão 1: pipeline de vídeos de vendas personalizados

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 guia de vídeos de vendas para dicas de roteiro e distribuição.

Padrão 2: lançamento de conteúdo multilíngue

Gere a mesma mensagem em vários idiomas com a 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 guia multilíngue para dicas de voz e tradução.

Padrão 3: automação de resumo diário de notícias

Pipeline agendado que busca 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="Professional news studio, broadcast style, medium close-up",
        resolution="720p",
    )
    return job["job_id"]

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

Veja guia de âncora de notícias.

Padrão 4: geração de vídeo acionada por CMS

Quando um novo post 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}

Boas práticas de tratamento de erros

Nova tentativa 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

Valide as entradas antes de enviar

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

• A URL da imagem retorna 200 e content-type image/*
• A URL do áudio retorna 200 e content-type audio/*
• A duração do áudio está dentro do limite para a resolução escolhida
• O prompt não está vazio

Trate limites de taxa

A API aplica limites de taxa. Respeite as respostas 429 e recue adequadamente.

Monitore o saldo de créditos

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

Gestão de custos

Um vídeo gerado pela API custa 2,4 créditos por segundo de áudio, ou seja, 72 créditos ($7,20) por 30 segundos. Os mesmos créditos que alimentam a interface alimentam a API:

Para cargas de trabalho intensas de API, o plano Studio oferece o melhor custo efetivo por geração. Veja guia de preços para mais detalhes.

Estimando o custo do projeto

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

total_cost = number_of_videos * 4.60

Um lote de 1.000 vídeos de 30 segundos: $7.200 na taxa base, e muito menos em um plano mensal. Planeje seu orçamento adequadamente.

Observabilidade

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

• Taxa de sucesso - % de jobs concluídos com êxito
• Tempo médio de geração - para planejamento de capacidade
• Créditos consumidos - totais acumulados para controle de orçamento
• Taxa de entrega de webhooks - detecte falhas na entrega de webhooks
• Categorização de erros - agrupe falhas por causa

Registre os IDs de job junto com seus IDs de correlação internos para facilitar a depuração.

Boas práticas de segurança

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

Primeiros passos com a API

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

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

Pronto para experimentar o OmniHuman v1.5? Comece a criar grátis →