Blog

Tutorial

Cómo llamar a seedance-2.5-flash reference-to-video mediante la API de HiAPI (curl + Python)

Solicitudes que funcionan, un script de Python ejecutable y cómo gestionar el sondeo de tareas asíncronas

Nov 19, 2026
Imagen de portada de estilo arquitectónico minimalista: planos de hormigón gris cálido entrelazados bajo un ángulo de luz solar rasante, acentuados por una superficie de sombra azul grisácea profunda y una fina junta verde salvia.
En esta página

Qué significa reference-to-video en la práctica

Reference-to-video es un modo de generación en el que le das al modelo dos cosas a la vez: un prompt de texto que describe el movimiento y la escena, y uno o varios materiales de referencia que anclan el contenido visual. El prompt aporta la intención («acercamiento lento, el personaje gira y sonríe»); los materiales de referencia aportan la identidad y la apariencia (un personaje, un producto, un estilo visual).

El endpoint del modelo para este flujo de trabajo es seedance-2.5-flash/reference-to-video, servido a través de la API unificada de HiAPI. Envías el model, el prompt y los materiales de referencia juntos en un único cuerpo de solicitud. No hay un paso de subida independiente que debas orquestar ni un registro por material que mantener.

La consecuencia práctica es que se trata de una operación de larga ejecución. Un vídeo corto sigue tardando mucho más en renderizarse que una completación de texto, por lo que la API trata la llamada como una tarea asíncrona. Tu solicitud crea la tarea; una segunda llamada obtiene el resultado. Esta forma de «enviar primero y sondear después» es el punto más importante al diseñar, y es la dirección que construye el resto de este tutorial.

Todo lo siguiente se mantiene dentro de la interfaz de HiAPI: una URL base, una cabecera de autenticación, una familia de endpoints.

Antes de enviar la primera solicitud

Hay tres cosas que preparar antes de la primera llamada.

1. La clave de API

Crea la clave en la consola de HiAPI y mantenla fuera del control de versiones. Los ejemplos siguientes la leen de una variable de entorno:

export HIAPI_API_KEY="your_key_here"

Si no estás seguro del formato actual de la clave o de la convención de cabeceras, consulta la documentación de la API de la plataforma en la consola; no lo adivines ni codifiques la clave directamente en un script que puedas compartir.

2. La URL base y la cabecera de autenticación

Todas las llamadas van a la URL base de HiAPI y llevan tu clave en la cabecera Authorization. Defínela una vez como variable para que cada solicitud sea coherente:

export HIAPI_BASE_URL="https://api.hiapi.ai"

Usa la URL base exactamente como se describe en la documentación de tu cuenta: una barra final que no coincide es una causa habitual de 404 confusos.

3. El endpoint del modelo

Tu objetivo es seedance-2.5-flash/reference-to-video. Referéncialo con este identificador en el cuerpo de la solicitud, no lo incrustes en la ruta, de modo que cambiar de modelo más adelante sea solo cambiar una línea.

También necesitas que los materiales de referencia sean accesibles por URL (o mediante la forma de material que especifique la documentación del endpoint). Hospédalos y hazlos públicamente accesibles antes de empezar: una URL de referencia rota es la causa más frecuente de que una tarea se envíe correctamente pero falle durante la generación.

Con estos tres elementos configurados, ya puedes construir el cuerpo de la solicitud.

Construir el cuerpo de la solicitud con materiales de referencia

El cuerpo de la solicitud tiene tres partes conceptuales: qué modelo usar, qué quieres y a qué haces referencia.

El modelo

Establece model en seedance-2.5-flash/reference-to-video. Trátalo como un campo de cadena normal: sin codificación URL, sin segmento de ruta.

El prompt

Escribe el prompt como una descripción de plano, no como una lista de deseos. Indica el sujeto, la acción, el comportamiento de la cámara y el ritmo. «Una persona con chaqueta roja camina hacia la cámara, plano medio, acercamiento lento, luz suave de día» da mucha más información al modelo que «un vídeo bonito de una persona». Mantén el prompt coherente con los materiales de referencia que proporcionas: si dos referencias muestran personajes distintos, especifica cuál es el dominante.

Los materiales de referencia

Los materiales de referencia son exactamente lo que distingue a este endpoint de una llamada normal de texto a vídeo. Pasas uno o varios materiales que definen lo que debe mantenerse consistente entre fotogramas. Reglas prácticas que ahorran iteraciones:

  • Usa el número mínimo de materiales de referencia que determine la identidad. Una referencia fuerte suele superar a cuatro mediocres.
  • Mantén los materiales de referencia coherentes entre sí. Ángulos o estilos en conflicto provocan deriva en la salida.
  • Prefiere fuentes limpias y bien iluminadas. Las referencias recortadas, borrosas o con filtros intensos propagan esos defectos.
  • Verifica que cada URL resuelve antes de enviar: descárgala tú mismo una vez.

Cómo se estructuran exactamente los materiales de referencia en el cuerpo de la solicitud (nombre del campo de array, estructura del objeto, tipos de material admitidos) debe provenir del esquema de solicitud del endpoint en la documentación de HiAPI. Construye el cuerpo según ese esquema, no de memoria; el esquema es la fuente autoritativa de los nombres de campo, y una clave que no coincide provoca fallos silenciosos.

Valida el JSON localmente antes de que la solicitud llegue a la red (python -m json.tool body.json). Un cuerpo mal formado es el error más fácil de detectar y el más molesto de depurar a partir de una traza de pila.

La solicitud curl que funciona

El siguiente comando sigue el patrón de enviar primero y sondear después: crea la tarea e imprime la respuesta JSON, que contiene el identificador de tarea que usarás para sondear.

curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-flash/reference-to-video",
    "prompt": "Una persona con chaqueta roja camina hacia la cámara, plano medio, acercamiento lento, luz suave de día",
    "references": [
      "https://your-cdn.example.com/refs/character-front.png",
      "https://your-cdn.example.com/refs/character-side.png"
    ]
  }'

Sustituye las URL de referencia por materiales alojados por ti y, antes de que el código de producción dependa de esto, confirma la ruta del endpoint y los nombres de campo con la página del modelo en la documentación de HiAPI: los detalles del esquema son autoritativos y este fragmento es solo ilustrativo.

Qué buscar en la respuesta:

  • Un id (o identificador de task/job): captúralo; lo necesitarás en cada sondeo.
  • Un campo status que indique que la tarea ha sido aceptada.
  • Cualquier advertencia sobre materiales ignorados o rechazados.

Formatea la respuesta para leerla mejor:

curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json | python -m json.tool

Guardar el cuerpo de la solicitud en body.json merece ese pequeño esfuerzo extra: se versiona limpiamente, se compara de forma legible y elimina los errores de comillas del shell del ámbito de depuración.

La misma llamada en Python

La siguiente es la llamada equivalente en Python, escrita para ejecutarse directamente una vez configuradas las variables de entorno. Usa solo la biblioteca estándar, así que no hay nada que instalar.

import json
import os
import urllib.request

BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]


def submit_reference_video(prompt, references):
    body = {
        "model": "seedance-2.5-flash/reference-to-video",
        "prompt": prompt,
        "references": references,
    }
    req = urllib.request.Request(
        f"{BASE_URL}/v1/videos/generations",
        data=json.dumps(body).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=60) as resp:
        payload = json.loads(resp.read().decode("utf-8"))
    return payload


if __name__ == "__main__":
    result = submit_reference_video(
        prompt="Una persona con chaqueta roja camina hacia la cámara, plano medio, acercamiento lento, luz suave de día",
        references=[
            "https://your-cdn.example.com/refs/character-front.png",
            "https://your-cdn.example.com/refs/character-side.png",
        ],
    )
    print(json.dumps(result, indent=2))
    job_id = result.get("id")
    print("job id:", job_id)

Dos detalles importan más de lo que parece. Primero, timeout=60: la llamada de envío debe devolver rápido, pero una conexión colgada es peor que un fallo rápido. Segundo, result.get("id") gestiona los casos en que la estructura de la respuesta es inesperada, en lugar de lanzar un KeyError en tu ruta normal.

Si prefieres requests o httpx, la conversión es directa: la misma URL, las mismas cabeceras, el mismo cuerpo JSON. La construcción del cuerpo es la parte que merece copiarse; el cliente HTTP es intercambiable.

Sondear la tarea asíncrona hasta que termine

La generación de vídeo no es una solicitud que puedas esperar. Envías, recibes el identificador y luego compruebas el estado periódicamente hasta que la tarea alcanza un estado terminal. Dos características hacen que esto sea seguro: el sondeo tiene un coste bajo y la llamada de envío ya ha hecho el trabajo costoso.

El bucle

import time

def wait_for_video(job_id, timeout_s=600, interval_s=5):
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        req = urllib.request.Request(
            f"{BASE_URL}/v1/videos/generations/{job_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        with urllib.request.urlopen(req, timeout=30) as resp:
            job = json.loads(resp.read().decode("utf-8"))

        status = job.get("status")
        if status in ("succeeded", "completed"):
            return job
        if status in ("failed", "error", "cancelled"):
            raise RuntimeError(f"job {job_id} ended with status {status}: {job.get('error')}")
        time.sleep(interval_s)

    raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")

Un bucle más apretado no será más rápido; solo consumirá límites de tasa. Para tareas de vídeo, un intervalo de cinco segundos es un valor predeterminado razonable.

Notas de diseño

  • Establece siempre una fecha límite. Una tarea que nunca termina jamás debe dejar colgado un hilo de solicitud para siempre.
  • Trata los estados desconocidos como «sigue esperando», no como éxito. Solo un éxito explícito es éxito.
  • No sondees dentro de un manejador de solicitudes web. Envía en el manejador, devuelve el id de tarea al cliente y deja que un proceso de trabajo en segundo plano sondee y persista el resultado.
  • Persiste el id de tarea y las transiciones de estado para que un proceso interrumpido pueda reanudarse en lugar de reenviar y pagar dos veces el renderizado.

Esta separación de enviar primero y sondear después es lo que permite que un flujo de vídeo lento se sitúe detrás de una API rápida.

Errores comunes y cómo solucionarlos

Casi todos los fallos de la primera hora entran en una de cuatro categorías. Compruébalas en este orden.

1. Autenticación

Síntoma: una respuesta de no autorizado o prohibido antes de crear ninguna tarea.

Comprueba: ¿está realmente poblada HIAPI_API_KEY en el shell o proceso que ejecuta el script? ¿La cabecera es exactamente Authorization: Bearer <key>? ¿Cargas la clave al importar cuando el script espera usarla más tarde? Imprime los primeros caracteres de la clave resuelta (nunca la clave completa) y confirma que no es una cadena vacía.

2. Ruta del endpoint

Síntoma: no encontrado, normalmente de inmediato.

Comprueba: exactamente una barra entre la URL base y la ruta; por eso el ejemplo de Python llama a .rstrip("/"). Confirma la ruta de generación y la ruta de sondeo con la página del modelo en la documentación; una URL de sondeo a la que le falta el segmento del id de tarea dará 404 siempre. Una barra final que el servidor no espera produce el mismo síntoma.

3. Cuerpo de solicitud mal formado

Síntoma: error de validación, o tarea aceptada que falla inmediatamente después.

Comprueba: ejecuta json.dumps(body) y revísalo. ¿Coincide model exactamente con seedance-2.5-flash/reference-to-video? ¿El campo de referencias es un array y cada entrada es una URL de cadena que resuelve en el navegador? ¿Enviaste Content-Type: application/json? Pasa el cuerpo por python -m json.tool para descartar errores de sintaxis antes de que llegue a la red.

4. Estado de la tarea

Síntoma: la llamada de envío se realiza correctamente, pero la tarea falla o nunca termina.

Comprueba: lee el campo de error en la respuesta de estado; normalmente indica la causa, con mayor frecuencia un material de referencia inalcanzable o no admitido. Si la tarea simplemente se queda parada, confirma que estás sondeando el id correcto y que la comparación de estados del bucle cubre los estados terminales que la API devuelve realmente. Registra cada transición de estado; el último estado antes del fallo es tu base de diagnóstico.

Una regla que acorta las cuatro categorías de diagnóstico: registra el id de solicitud y el id de tarea de cada llamada. Cuando algo falla, un id convierte un informe de error vago en una búsqueda concreta.

Siguientes pasos

Ya tienes la forma completa: construir el cuerpo con prompt y materiales de referencia, enviarlo, sondear hasta el estado terminal y gestionar las cuatro categorías de fallo comunes. A partir de aquí, los siguientes pasos naturales son de ingeniería, no de API.

  • Envuelve el envío en reintentos con retroceso exponencial para errores de red transitorios, pero nunca reintentes una tarea que ya tiene id: eso es un renderizado duplicado.
  • Mueve el sondeo a un proceso de trabajo o a una cola para que la capa HTTP siga respondiendo y las tareas sobrevivan a los reinicios de proceso.
  • Almacena el id de tarea junto con tus propios metadatos de solicitud (prompt, materiales de referencia, usuario solicitante) para que los resultados sigan siendo rastreables meses después.
  • Valida los materiales de referencia antes de aceptarlos: descarga cada URL cuando el usuario la proporcione y luego gasta la tarea.

Para el esquema de solicitud autoritativo, las formas de material admitidas y los detalles actuales del endpoint, consulta la página del modelo seedance-2.5-flash reference-to-video en HiAPI. Construye según ese esquema, mantén la separación de enviar primero y sondear después, y la integración seguirá siendo aburrida, que es exactamente lo que quieres de un flujo de vídeo.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API