OmniHuman v1.5 API: Generación Programática de Videos de Avatar

Ejecutar OmniHuman v1.5 a través de la interfaz de Arteza es excelente para creaciones puntuales. Para flujos de trabajo de alto volumen, como alcance de ventas personalizado, lanzamientos multilingües, generación de vídeos impulsada por CMS y resúmenes de noticias automatizados, necesitas la API. Esta guía recorre la autenticación, los extremos, la estructura de solicitud, el manejo de webhooks y los patrones de producción. Cada generación cuesta lo mismo: 960 créditos ($9.60), ya sea que la invoques a través de la interfaz o de la API.

Resumen

• Genera vídeos de OmniHuman v1.5 mediante programación a través de la API REST de Arteza
• Los mismos $9.60 por generación que en la interfaz, sin sobrecargo de API
• Generación asincrónica con recuperación de resultados basada en webhook o encuesta
• Ideal para vídeo de ventas personalizado, bibliotecas de capacitación automatizadas, lanzamientos multilingües
• Autenticación mediante clave de API de tu panel de Arteza

Por qué usar la API

La API desbloquea patrones de automatización que la interfaz no puede ofrecer:

• Generación por lotes. Ejecuta más de 100 vídeos en una sola ejecución de canalización.
• Personalización dinámica. Extrae datos de un CRM y genera un vídeo por prospecto.
• Flujos de trabajo programados. Resúmenes de noticias diarios, vídeos de resumen semanal, actualizaciones desencadenadas.
• Integración con pilas existentes. Node.js, Python, Go, Ruby: cualquier lenguaje con HTTP puede llamarla.
• Producción reproducible. Scripts controlados por versión en lugar de clics manuales en la interfaz.

Si tu caso de uso implica más de 10 vídeos con estructura similar, vale la pena configurar la API.

Autenticación

Las solicitudes de la API de Arteza se autentican mediante una clave de API pasada en el encabezado Authorization como un token portador.

Obtén tu clave de API

1. Inicia sesión en arteza.ai
2. Navega a la configuración de tu cuenta
3. Encuentra la sección de API
4. Genera una nueva clave de API
5. Guárdala de forma segura: trátala como una contraseña

Nunca confirmes tu clave de API en el control de código fuente. Usa variables de entorno:

export SEEDANCE_API_KEY="tu_clave_api_aqui"

Encabezado de autenticación

Cada solicitud incluye:

Authorization: Bearer TU_SEEDANCE_API_KEY
Content-Type: application/json

Estructura del extremo

La API de OmniHuman v1.5 sigue patrones de generación asincrónica estándar:

• POST para crear una tarea de generación
• GET para consultar el estado y los resultados
• Webhook para entrega asincrónica (recomendado para producción)

URL base

https://api.arteza.ai/v1

Extremos clave

Consulta la documentación de la API de Arteza en directo para las rutas exactas de los extremos, ya que pueden cambiar.

Envío de una tarea de generación

Estructura de solicitud

{
  "model": "omnihuman-v1.5",
  "image_url": "https://example.com/portrait.jpg",
  "audio_url": "https://example.com/speech.mp3",
  "prompt": "Oficina corporativa moderna con iluminación natural suave, encuadre de primer plano medio cabeza y hombros, estilo de transmisión profesional",
  "resolution": "1080p",
  "turbo_mode": false,
  "webhook_url": "https://yourapp.com/webhooks/seedance"
}

Referencia de parámetros

Requisitos de archivo de entrada

Imagen:

• Formatos: JPEG, PNG
• Resolución: mínimo 512x512, se recomienda 1024x1024+
• Accesible mediante URL HTTPS pública

Audio:

• Formatos: MP3, WAV, M4A
• Duración: ≤60s para 720p, ≤30s para 1080p
• Accesible mediante URL HTTPS pública

Si tus archivos no están alojados públicamente, súbelos a S3, Cloudflare R2, Google Cloud Storage o similar antes de hacer la llamada a la API.

Ejemplo de solicitud en 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']}")

Ejemplo de solicitud en 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 de respuesta

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

El job_id es lo que usas para consultar o correlacionar entregas de webhook.

Encuesta de resultados

Si no usas webhooks, consulta el extremo de estado del trabajo hasta que se complete.

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

Valores de estado del trabajo

Uso de webhooks (recomendado para producción)

Los webhooks eliminan la encuesta y te permiten crear canalizaciones impulsadas por eventos.

Configuración de un webhook

Pasa webhook_url en tu solicitud de generación. Seedance PUBLICA en esa URL cuando el trabajo se completa.

Carga útil 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"
}

Ejemplo de controlador 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"]

        # Tu lógica empresarial: descarga el vídeo, notifica a los usuarios,
        # desencadena flujos de trabajo descendentes, etc.
        handle_completed_video(job_id, video_url)

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

Seguridad de webhook

Verifica las firmas de webhook si Arteza proporciona un secreto de firma. Siempre valida que los webhooks provengan de Arteza antes de actuar en función de ellos.

¿Listo para probar OmniHuman v1.5? Comienza a crear gratis →

¿Quieres un presentador como este? Prueba OmniHuman gratis →

Patrones de producción

Patrón 1: Canalización de vídeo de ventas personalizado

Genera un vídeo por prospecto con variables 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)

Consulta guía de videos de ventas para secuencias de comandos y distribución.

Patrón 2: Lanzamiento de contenido multilingüe

Genera el mismo mensaje en varios idiomas, misma 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 guía multilingüe para consejos de voz y traducción.

Patrón 3: Automatización de resumen de noticias diarias

Canalización programada que extrae titulares, genera TTS y produce un vídeo diario.

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

# Programa mediante cron, Airflow o tu herramienta de flujo de trabajo
daily_news_digest()

Consulta guía de presentador de noticias.

Patrón 4: Generación de vídeo desencadenada por CMS

Cuando se publica una nueva entrada de blog o producto, genera un vídeo complementario.

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

Mejores prácticas de manejo de errores

Reintentar con retroceso exponencial

Los errores de red y los fallos transitorios deben desencadenar reintentos, no abandono inmediato.

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 entradas antes de enviar

Ahorra créditos validando antes de cada llamada a la API:

• La URL de la imagen devuelve 200 y content-type image/*
• La URL de audio devuelve 200 y content-type audio/*
• La duración del audio está dentro del límite para la resolución elegida
• El aviso no está vacío

Manejo de límites de velocidad

La API impone límites de velocidad. Respeta las respuestas 429 y retrocede adecuadamente.

Monitorea el saldo de créditos

Comprueba tu saldo de créditos antes de ejecutar lotes grandes. Quedarse sin créditos a mitad del lote es evitable.

Gestión de costes

Cada vídeo generado por API cuesta 960 créditos ($9.60). El mismo paquete de créditos que potencia la interfaz potencia la API:

Para cargas de trabajo de API pesadas, el nivel Máximo te ofrece el mejor coste efectivo por generación. Consulta guía de precios para obtener detalles.

Estimación del coste del proyecto

Antes de iniciar una ejecución de lote, calcula el coste total:

coste_total = número_de_vídeos * 9.60

Un lote de 1,000 vídeos: $9,600 tarifa base, ~$8,000 en nivel Máximo. Presupuesta en consecuencia.

Observabilidad

Para flujos de trabajo de producción, realiza un seguimiento de estas métricas:

• Tasa de éxito: % de trabajos que se completan con éxito
• Tiempo medio de generación: para la planificación de capacidad
• Créditos consumidos: totales rodantes para el seguimiento de presupuesto
• Tasa de entrega de webhook: detecta fallos en la entrega de webhooks
• Categorización de errores: agrupa fallos por causa

Registra los ID de trabajo junto con tus ID de correlación internos para la depuración.

Mejores prácticas de seguridad

• Nunca expongas tu clave de API en el lado del cliente. Siempre llama a la API desde tu backend.
• Usa variables de entorno o un gestor de secretos. Nunca confirmes claves en el control de código fuente.
• Rota las claves periódicamente. Trátalas como cualquier otra credencial.
• Valida las firmas de webhook cuando esté disponible.
• Usa HTTPS para todas las URLs de imagen y audio que pases a la API.
• Establece el alcance de los extremos de webhook para que solo se procesen cargas útiles legítimas de Arteza.

Comenzar con la API

1. Regístrate en Arteza y recibe 50 créditos gratuitos
2. Compra al menos un paquete Inicio ($10) para tener suficiente para una generación de prueba
3. Genera tu clave de API en el panel de control
4. Prepara un archivo de imagen y audio de prueba, sube a una URL pública
5. Realiza tu primera llamada a la API usando los ejemplos anteriores
6. Consulta o espera webhook para recuperar la URL del vídeo
7. Construye tu canalización de producción

Para lecturas relacionadas, consulta guía completa de OmniHuman v1.5, desglose de precios, guía de videos de ventas y guía multilingüe.

¿Listo para probar OmniHuman v1.5? Comienza a crear gratis →