Blog

Tutorial

Tutorial de la API muse-video-1.0 de imagen a vídeo: curl y Python Requests

Nov 13, 2026
Ilustración de portada del tutorial de muse-video-1.0: sección transversal mineral facetada plana en verde azulado sobre un fondo azul petróleo profundo.
En esta página

Qué requiere el endpoint muse-video-1.0 de imagen a vídeo

El endpoint muse-video-1.0/image-to-video convierte una única imagen estática en un vídeo corto. Antes de escribir la primera línea de código, comprender la estructura de la solicitud te ayuda a componer la carga útil correcta a la primera.

Desde un punto de vista general, una llamada implica cuatro aspectos:

  • Enrutamiento del modelo —— especificas el modelo mediante muse-video-1.0/image-to-video a través de la API unificada de HiAPI.
  • Imagen de entrada —— el fotograma estático que sirve como punto de partida de la animación. Es la entrada creativa obligatoria.
  • Opciones de generación —— el comportamiento del audio y el nivel de duración, que moldean las características de la salida y no el material de origen.
  • Ejecución asíncrona —— la generación no devuelve el vídeo final de forma síncrona. Primero envías la tarea y después consultas el resultado mediante sondeo.

Este último punto es el que los desarrolladores pasan por alto con más frecuencia. Dado que el renderizado lleva tiempo, el endpoint se basa en un mecanismo de tareas: la llamada inicial confirma tu solicitud y devuelve un identificador, y luego sigues consultando el estado hasta que el vídeo esté listo. Diseña tu cliente en torno a este flujo de dos fases desde el principio, en lugar de añadir el sondeo a posteriori.

El cuerpo de la solicitud es JSON. Los campos se agrupan por estructura: la imagen se encuentra en un bloque input independiente, mientras que el audio y la duración están a su lado como ajustes de generación. Mantén este modelo mental —— entrada, opciones y ciclo de vida de la tarea separados —— y el resto del tutorial resultará directo.

Autenticación

Cada solicitud se autentica con tu clave de API de HiAPI, en forma de credencial bearer en la cabecera Authorization. Trata la clave como un secreto: cárgala desde una variable de entorno en lugar de codificarla directamente en scripts que puedas compartir.

export HIAPI_API_KEY="your_api_key_here"

Una vez exportada la clave, ya tienes todo lo necesario para comprender la solicitud. Las secciones siguientes construirán la carga útil paso a paso.

Prepara y sube tu imagen del primer fotograma

La imagen del primer fotograma es el ancla creativa de toda la tarea. El contenido que proporciones se convertirá en el fotograma cero, y el modelo animará a partir de ahí. Acertar con esto evita desperdiciar generaciones.

Consejos prácticos para el fotograma de origen

  • Usa una imagen estática clara y de alta calidad. Lo que se lee bien como fotograma único ofrece al modelo el mejor punto de partida.
  • Elige una relación de aspecto que coincida con la salida objetivo. Una imagen horizontal ancha y una vertical alargada producen composiciones muy distintas, así que decide la orientación antes de subir nada.
  • Evita el desenfoque de movimiento intenso o los sujetos poco definidos. Una imagen estática visualmente estable genera una animación más predecible.
  • Asegúrate de que el archivo sea accesible en el momento de la solicitud. Tanto si pasas una URL como una carga codificada, garantiza que la referencia sea alcanzable en el instante en que se envía la tarea.

Cómo entra la imagen en la solicitud

La imagen se proporciona en el bloque input del cuerpo JSON. Una entrada de imagen mínima tiene este aspecto:

{
  "input": {
    "image": "https://your-host.example/first-frame.jpg"
  }
}

Si tu imagen de origen está almacenada localmente, alójala en una ubicación accesible para la solicitud o pásala en la forma codificada que acepte el endpoint. La regla clave es: el valor de input.image debe resolverse en contenido de imagen real en el momento de crear la tarea —— un enlace roto o caducado fallará en el envío, no durante el sondeo, lo que en realidad es una señal temprana útil.

Verifica antes de generar

Una comprobación rápida de sanidad vale la pena: abre la URL de la imagen en el navegador, confirma que carga y después confirma que sus dimensiones encajan con la salida que esperas. Dos segundos de revisión aquí evitan un proceso de depuración confuso más adelante.

Con el primer fotograma listo y accesible, ya puedes pasar a las opciones de generación.

Configura los parámetros de audio y el nivel de duración

Además de la imagen, muse-video-1.0/image-to-video ofrece dos tipos de opciones que modifican las características de la salida: el comportamiento del audio y la duración.

Parámetro de audio

El audio se representa mediante un campo del cuerpo de la solicitud, junto a tu input. Define la intención antes de llamar:

  • Salida silenciosa —— si planeas añadir tu propia banda sonora en posproducción o necesitas una pista de vídeo limpia, mantén el audio desactivado.
  • Audio activado —— si el clip debe tener sonido propio, activa el audio. Comprueba explícitamente esta opción en la carga útil en lugar de asumir un valor predeterminado.

Dado que el procesamiento de audio es una propiedad de la propia solicitud y no un paso de posprocesamiento, conviene fijarlo antes de escalar. Si tu canal combina clips silenciosos y con audio, modela esa elección como un parámetro explícito en tu propio código de cliente para evitar que ocurra por accidente.

Nivel de duración

El endpoint te permite elegir el nivel de duración del clip. Trata la duración como una decisión intencionada tanto creativa como de coste:

  • Niveles más cortos son adecuados para previsualizaciones rápidas, clips sociales y pruebas de storyboard, donde quieres obtener retroalimentación rápida sobre muchas imágenes de origen.
  • Niveles más largos dan a la animación más espacio para desarrollarse y encajan mejor en planos principales o secuencias que necesitan respirar.

La duración se factura por segundos de salida, por lo que el nivel que elijas afecta directamente al consumo. No hay ninguna ventaja en renderizar clips largos solo para una comprobación visual rápida —— usa niveles cortos mientras iteras sobre el primer fotograma y luego promociona la configuración ganadora a un nivel más largo.

Ensambla estas opciones juntas

En JSON, los ajustes de audio y duración van junto al bloque input:

{
  "input": {
    "image": "https://your-host.example/first-frame.jpg"
  },
  "audio": true,
  "duration": "<duration_tier>"
}

Usa los identificadores exactos de nivel que se indican en la documentación del endpoint, en lugar de adivinar valores. La siguiente sección lo convierte en una solicitud ejecutable.

Una solicitud curl que funciona

Con la carga útil ensamblada, aquí está el comando curl para el envío inicial. Crea la tarea; no devuelve el vídeo final.

curl -X POST "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "image": "https://your-host.example/first-frame.jpg"
    },
    "audio": true,
    "duration": "<duration_tier>"
  }'

Algunas notas sobre este comando:

  • La URL nombra el modelo. No necesitas un cliente distinto para cada modelo; la ruta ya identifica muse-video-1.0/image-to-video.
  • La cabecera transporta tu clave. $HIAPI_API_KEY se expande desde la variable de entorno que exportaste antes, así que la clave nunca aparece en el propio script.
  • El cuerpo es la carga útil que acabas de construir. La URL de la imagen, el indicador de audio y el nivel de duración se envían juntos.

La respuesta es una confirmación de tarea: contiene el identificador de la tarea que acabas de crear. Copia ese identificador —— lo usarás en el paso de sondeo. Si solo estás explorando, puedes procesar la respuesta con una herramienta de formateo JSON para localizar el job ID más fácilmente.

Si el envío falla, el error suele ser inmediato y concreto: cuerpo JSON mal formado, referencia de imagen ausente o valor de opción no reconocido. Este bucle de retroalimentación rápida es precisamente la razón por la que conviene probar el envío por separado antes de conectar el sondeo.

La misma solicitud en Python

La mayoría de las integraciones acaban en Python, así que aquí tienes el envío equivalente usando la biblioteca estándar —— sin SDK de terceros.

import json
import os
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video"

payload = {
    "input": {
        "image": "https://your-host.example/first-frame.jpg"
    },
    "audio": True,
    "duration": "<duration_tier>",
}

request = urllib.request.Request(
    ENDPOINT,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    method="POST",
)

with urllib.request.urlopen(request) as response:
    result = json.loads(response.read().decode("utf-8"))

job_id = result["id"]
print("Submitted job:", job_id)

Este script corresponde campo por campo a la llamada curl. Algunos hábitos que vale la pena adoptar:

  • Mantén la carga útil en un diccionario. Construirla como un diccionario de Python significa que puedes pasar la misma estructura a cualquier biblioteca HTTP —— urllib, requests o un cliente asíncrono —— sin reescribir la lógica.
  • Lee la clave desde el entorno. os.environ mantiene las credenciales fuera del control de código fuente.
  • Analiza la respuesta como JSON de inmediato. Extrae el job ID en una variable con nombre para que el paso de sondeo se lea con más claridad.

Si prefieres la biblioteca requests, el único cambio es la capa de transporte: construye el mismo diccionario payload y envíalo con tu conjunto de cabeceras, y luego llama a .json() sobre la respuesta. El endpoint, las cabeceras y el cuerpo permanecen exactamente iguales.

Una vez enviada la tarea y capturado su identificador, lo que queda es esperar el resultado de la forma correcta.

Sondea la tarea asíncrona y obtén el vídeo

La generación de vídeo no es instantánea, por lo que el endpoint es asíncrono. Tras el envío, consultas el estado de la tarea para saber cuándo ha terminado el renderizado y luego recuperas la salida.

Bucle de sondeo

Un bucle robusto hace tres cosas: espera entre comprobaciones, establece un límite para no ejecutarse indefinidamente y distingue entre «aún en proceso», «completado» y «fallido».

import time
import urllib.request

STATUS_ENDPOINT = "https://api.hiapi.ai/v1/jobs/{job_id}"

def wait_for_video(job_id, max_attempts=60, interval=5):
    for attempt in range(max_attempts):
        url = STATUS_ENDPOINT.format(job_id=job_id)
        request = urllib.request.Request(
            url,
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        with urllib.request.urlopen(request) as response:
            status = json.loads(response.read().decode("utf-8"))

        state = status.get("status")
        if state == "succeeded":
            return status.get("output")
        if state == "failed":
            raise RuntimeError(f"Job {job_id} failed: {status}")

        time.sleep(interval)

    raise TimeoutError(f"Job {job_id} did not finish in time")

Puntos de diseño para producción

  • Usa un intervalo razonable. Cinco segundos es un punto de partida sensato; no bombardees el endpoint de estado.
  • Limita siempre el número de intentos. El límite de max_attempts convierte una espera infinita en un error claro que puedes registrar y sobre el que puedes alertar.
  • Gestiona los estados de fallo de forma explícita. Las tareas fallidas incluyen información de diagnóstico —— expónla en lugar de reintentar silenciosamente la misma entrada.
  • Persiste el job ID. Si tu proceso se reinicia, puedes reanudar el sondeo en lugar de pagar por volver a generar.

Obtén la salida

Cuando la tarea tiene éxito, la respuesta de estado incluye la referencia de salida del vídeo final. Descárgalo a tu propio almacenamiento de forma oportuna en lugar de depender de enlaces de larga duración. Una vez que tengas el archivo en local o en un bucket, la generación habrá terminado desde la perspectiva de tu canal.

Ese es todo el ciclo de vida: enviar, sondear, obtener. Separa las dos fases en el código y cada una se mantendrá sencilla.

Errores comunes y consejos de depuración

La mayoría de los problemas de integración con muse-video-1.0/image-to-video se pueden agrupar en unas pocas categorías. Esto es lo que debes revisar cuando algo falla.

Problemas con la entrada de imagen

  • Referencia de imagen inalcanzable. Si la URL requiere autenticación o ha caducado, la tarea fallará al enviarse. Aloja el fotograma en una ubicación de lectura pública durante la solicitud.
  • Relación de aspecto no coincidente. Forzar una imagen estática vertical en una salida horizontal produce recortes incómodos o barras negras. Ajusta la orientación de origen para que coincida con el objetivo.
  • Contenido incorrecto. Es fácil apuntar a una miniatura o a una imagen de marcador de posición en lugar del fotograma real. Verifica que la URL abra la imagen prevista.

Errores de parámetros

  • Adivinar los valores de duración. Usa los identificadores exactos de nivel indicados en la documentación del endpoint. Los valores no reconocidos son una causa común de rechazo.
  • Olvidar el indicador de audio. Si omites el ajuste de audio pero esperas sonido, puedes obtener un clip silencioso. Sé explícito sobre si necesitas audio.
  • Confundir campos de nivel superior con campos de input. La imagen va dentro de input; el audio y la duración son hermanos de input, no hijos suyos. Un anidamiento incorrecto genera mensajes de validación confusos.

Errores de sondeo

  • Tratar el envío como finalización. La primera respuesta es solo una confirmación, no el vídeo. Haz siempre un seguimiento con la comprobación de estado.
  • Sondeo sin límites. Un bucle sin límite dejará tu worker colgado si la tarea se atasca. Añade un límite y un error de tiempo de espera.
  • Ignorar los fallos. Una tarea que termina en estado fallido nunca producirá un vídeo; captúralo y revisa el diagnóstico en lugar de seguir esperando.
  • Esperas prolongadas con entradas incorrectas. Cuando el renderizado falla repetidamente, deja de regenerar. Corrige primero el fotograma de origen o los parámetros y luego vuelve a enviar.

Un orden de depuración eficaz

  1. Confirma que la URL de la imagen carga en el navegador.
  2. Envía una carga útil mínima solo con la imagen para aislar problemas de parámetros.
  3. Verifica que el job ID se devuelve correctamente.
  4. Sondea manualmente primero para observar las transiciones de estado.
  5. Solo después de esto, automatiza el bucle y añade reintentos en torno a errores de red transitorios.

Abordar estos pasos en orden reduce rápidamente el problema a una capa concreta —— imagen, opciones o ciclo de vida —— y mantiene la integración en marcha. Una vez que comprendes la estructura de la solicitud, las opciones y el flujo de sondeo, estás listo para construir contra este endpoint.

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