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
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 →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio