API de OmniHuman v1.5: generación programática de videos con avatares

Usar OmniHuman v1.5 desde la interfaz de Arteza es ideal para creaciones puntuales. Para flujos de trabajo de alto volumen, como prospección de ventas personalizada, lanzamientos multilingües, generación de vídeo impulsada por CMS o resúmenes de noticias automatizados, lo que necesitas es la API. Esta guía explica la autenticación, los endpoints, la estructura de las solicitudes, el manejo de webhooks y los patrones de producción. Cada generación cuesta 3-72 créditos ($0,30-$7,20), independientemente de si la ejecutas desde la interfaz o desde la API.

Resumen rápido

• Genera vídeos con OmniHuman v1.5 de forma programática mediante la API REST de Arteza
• El mismo precio de $0,30-$7,20 por generación que en la interfaz, sin recargo por uso de la API
• Generación asíncrona con recuperación de resultados mediante webhook o sondeo
• Ideal para vídeos de ventas personalizados, bibliotecas de formación automatizadas y lanzamientos multilingües
• Autenticación mediante clave de API desde tu panel de Arteza

Por qué usar la API

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

• Generación en lote. Ejecuta más de 100 vídeos en una sola pasada.
• Personalización dinámica. Extrae datos de un CRM y genera un vídeo por prospecto.
• Flujos de trabajo programados. Resúmenes diarios de noticias, vídeos de resumen semanales y actualizaciones activadas por eventos.
• Integración con stacks existentes. Node.js, Python, Go, Ruby: cualquier lenguaje con HTTP puede llamarla.
• Producción reproducible. Scripts bajo control de versiones en lugar de clics manuales en la interfaz.

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

Autenticación

Las solicitudes a la API de Arteza se autentican mediante una clave de API que se pasa en el encabezado Authorization como token Bearer.

Cómo obtener tu clave de API

1. Inicia sesión en arteza.ai
2. Ve a la configuración de tu cuenta
3. Busca 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 incluyas tu clave de API en el control de versiones. Usa variables de entorno:

export SEEDANCE_API_KEY="your_api_key_here"

Encabezado de autenticación

Cada solicitud incluye:

Authorization: Bearer YOUR_SEEDANCE_API_KEY
Content-Type: application/json

Estructura de los endpoints

La API de OmniHuman v1.5 sigue los patrones estándar de generación asíncrona:

• POST para crear un trabajo de generación
• GET para consultar el estado y los resultados
• Webhook para entrega asíncrona (recomendado para producción)

URL base

https://api.arteza.ai/v1

Endpoints principales

Consulta la documentación en línea de la API de Arteza para conocer las rutas exactas de los endpoints, ya que pueden cambiar con el tiempo.

Enviar un trabajo de generación

Estructura de la solicitud

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

Referencia de parámetros

Requisitos de los archivos de entrada

Imagen:

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

Audio:

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

Si tus archivos no están alojados públicamente, súbelos a S3, Cloudflare R2, Google Cloud Storage o un servicio similar antes de realizar 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"Trabajo enviado: {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(`Error en la API de 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: "Modern office, soft lighting, medium close-up",
});
console.log(`Trabajo enviado: ${job.job_id}`);

Formato de la respuesta

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

El job_id es el valor que usarás para el sondeo o para correlacionar las entregas de webhook.

Sondeo de resultados

Si no utilizas webhooks, consulta el endpoint de estado del trabajo hasta que este 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"La generación falló: {data.get('error')}")

        time.sleep(poll_interval)

    raise TimeoutError("El trabajo no se completó dentro del tiempo límite")

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

Valores de estado del trabajo

Uso de webhooks (recomendado para producción)

Los webhooks eliminan el sondeo y te permiten construir pipelines orientados a eventos.

Configurar un webhook

Incluye webhook_url en tu solicitud de generación. Seedance envía una solicitud POST a esa URL cuando el trabajo se 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": 46,
  "completed_at": "2026-04-10T14:26:45Z"
}

Ejemplo de manejador 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 de negocio: descargar el vídeo, notificar a los usuarios,
        # activar flujos de trabajo posteriores, etc.
        handle_completed_video(job_id, video_url)

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

Seguridad del webhook

Verifica las firmas del webhook si Arteza proporciona un secreto de firma. Valida siempre que los webhooks provienen de Arteza antes de actuar sobre ellos.

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

¿Quieres un presentador como este? Prueba OmniHuman gratis →

Patrones de producción

Patrón 1: Pipeline de vídeos de ventas personalizados

Genera un vídeo por prospecto con variables de guion 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 el guía de videos de ventas para orientación sobre guiones y distribución.

Patrón 2: Lanzamiento de contenido multilingüe

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

Patrón 3: Automatización de resúmenes de noticias diarios

Pipeline programado 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 con cron, Airflow o tu herramienta de flujos de trabajo
daily_news_digest()

Consulta el guía de presentador de noticias.

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

Cuando se publica una nueva entrada de blog o un 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}

Buenas prácticas de manejo de errores

Reintentos con retroceso exponencial

Los errores de red y los fallos transitorios deben activar reintentos, no un 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

Validar las 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 del audio devuelve 200 y content-type audio/*
• La duración del audio está dentro del límite para la resolución elegida
• El prompt no está vacío

Gestionar los límites de velocidad

La API aplica límites de velocidad. Respeta las respuestas 429 y aplica el retroceso adecuado.

Monitorizar el saldo de créditos

Comprueba el saldo de créditos antes de ejecutar grandes lotes. Quedarse sin créditos a mitad de un lote es algo evitable.

Gestión de costes

Un vídeo generado por la API cuesta 2,4 créditos por segundo de audio, es decir, 72 créditos ($7.20) por 30 segundos. Los mismos créditos que alimentan la interfaz alimentan la API:

Para cargas de trabajo intensivas con la API, el plan Studio ofrece el coste efectivo más bajo por generación. Consulta el guía de precios para más detalles.

Estimar el coste del proyecto

Antes de iniciar un lote, calcula el coste total:

total_cost = number_of_videos * 4.60

Un lote de 1.000 vídeos de 30 segundos: $7,200 a la tarifa base, y bastante menos con un plan mensual. Planifica tu presupuesto en consecuencia.

Observabilidad

Para flujos de trabajo en producción, monitoriza estas métricas:

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

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

Buenas prácticas de seguridad

• Nunca expongas tu clave de API en el lado del cliente. Llama siempre a la API desde tu backend.
• Usa variables de entorno o un gestor de secretos. Nunca incluyas claves en el control de versiones.
• Rota las claves periódicamente. Trátalas como cualquier otra credencial.
• Verifica las firmas de los webhooks cuando estén disponibles.
• Usa HTTPS para todas las URL de imagen y audio que pases a la API.
• Limita el alcance de los endpoints de webhook para que solo se procesen los payloads legítimos de Arteza.

Primeros pasos con la API

1. Regístrate en Arteza y recoge tus 10 créditos gratuitos
2. Suscríbete al menos al plan Starter ($5/mes) para tener suficiente para una generación de prueba
3. Genera tu clave de API en el panel de control
4. Prepara una imagen y un archivo de audio de prueba y súbelos a una URL pública
5. Realiza tu primera llamada a la API usando los ejemplos anteriores
6. Sondea o espera el webhook para recuperar la URL del vídeo
7. Construye tu pipeline de producción

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

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