Tutorial de imagen a video

Ten una cuenta, saldo y una clave de API

Sigue primero Configura tu cuenta. Cuando termines, deberías tener:

• una cuenta de SpicyAPI con dinero en el saldo;
• una clave de API, que empieza por sk-spicy-;
• esa clave guardada en una variable de entorno llamada SPICY_API_KEY. Una variable de entorno es un valor con nombre que tu terminal entrega a los programas que ejecuta, así que la clave nunca tiene que aparecer en un comando ni en tu código.

Comprueba que la clave está configurada en la ventana de terminal que estás usando, sin mostrar la clave completa:

echo "${SPICY_API_KEY:0:9}"

Deberías ver sk-spicy-. Si no ves nada o aparece un error, la clave no está configurada en esta ventana; vuelve a Configura tu cuenta.

Pon tu imagen en una carpeta de trabajo

Crea una carpeta para este tutorial y abre la terminal en ella. Todos los comandos de esta página se ejecutan desde esa carpeta, y todos los archivos que crean acaban ahí.

mkdir -p ~/spicy-video
cd ~/spicy-video

Copia tu imagen en esa carpeta y llámala start-frame.jpg (o start-frame.png si es un PNG; en ese caso, usa ese nombre en todos los sitios donde esta página dice start-frame.jpg).

Qué hace que una imagen de partida funcione bien:

• Formato y tamaño: JPEG, PNG, WebP o GIF, hasta 10 MiB (unos 10 megabytes). Un modelo puede fijar sus propios límites, más estrictos, que verás en el paso 1.
• El archivo tiene que estar de verdad en ese formato. SpicyAPI comprueba el contenido del archivo, no solo su nombre. Las fotos hechas con el teléfono suelen estar en HEIC, y cambiarles la extensión a .jpg no las convierte. Abre la foto y expórtala o guárdala antes como JPEG.
• Forma: la imagen se convierte en el primer fotograma. Usa una imagen horizontal para un video horizontal y una vertical para un video vertical; algunos modelos ofrecen además un ajuste aspect_ratio.
• Derechos: usa una imagen que tengas permiso para usar.

Prepara la herramienta que elegiste

npm install -g @spicyapi/cli
spicyapi --version

spicyapi balance

1. Elige un modelo y lee sus ajustes

Qué hacer: lista los modelos de imagen a video que tu cuenta puede usar, elige uno y lee qué ajustes acepta.

spicyapi models list --modality video --task image-to-video --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example video model",
      "modality": "video",
      "tasks": ["image-to-video"],
      "enabled": true,
      "available": true,
      "quantityField": "duration_seconds",
      "maxOutputDurationSeconds": 10,
      "taskTimeoutSeconds": 1800,
      "pricing": [
        { "variant": "720p", "unit": "per_second", "price": "…", "currency": "USD" },
        { "variant": "1080p", "unit": "per_second", "price": "…", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

Qué mirar en la lista:

Cómo leer los ajustes. inputSchema es la lista de ajustes del modelo, escrita en JSON Schema:

• required enumera los ajustes que tienes que enviar. En este tipo de modelo, image_url siempre está entre ellos, y la mayoría exige también prompt.
• properties enumera todos los ajustes que acepta el modelo, cada uno con un type, una description en inglés sencillo y, a menudo, enum (los únicos valores permitidos), minimum y maximum, y default (el valor que se usa cuando omites el ajuste).
• Dentro de cada ajuste, x-ui contiene indicaciones de presentación. x-ui.affects_price: true significa que cambiar ese ajuste cambia el precio.
• Algunos modelos añaden condiciones en el nivel superior, como «si envías A, también tienes que enviar B». Spicy Schema explica cómo leerlas.
• examples contiene entradas completas que el servidor ya ha comprobado, y son un punto de partida seguro.

Los ajustes con los que más te vas a encontrar. Los nombres son iguales en todos los modelos, pero cada modelo acepta solo algunos, con sus propios valores permitidos:

Qué acaba de pasar: has leído el catálogo en vivo de tu cuenta, con tus precios. No se ha cobrado nada. Leer el catálogo cuenta para el límite de solicitudes de tu cuenta, así que no hace falta repetirlo antes de cada video; vuelve a hacerlo cuando cambies de modelo o recibas un 400.

2. Sube tu imagen

Qué hacer: sube start-frame.jpg y copia la dirección spicy:// que recibes. Subir es gratis.

spicyapi files upload start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z

Qué acaba de pasar: tu imagen se ha guardado de forma privada para tu cuenta, se ha comprobado (su formato real tiene que coincidir con su tipo) y ha recibido una dirección spicy://. Esa dirección no es un enlace web: solo tu cuenta puede usarla, y solo dentro de la entrada de una tarea. Se puede usar durante un día (mira expiresAt); pasado ese plazo, vuelve a subir la imagen.

Si la subida falla:

3. Describe el video y comprueba el precio

Qué hacer: escribe tus ajustes en un archivo llamado input.json y después pide una cotización.

Escribe input.json. Empieza con los dos ajustes que acepta cualquier modelo de imagen a video. Pon tu propia frase en prompt y sustituye el valor de image_url por el uri que copiaste en el paso 2:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}

Los ajustes que omitas usan el default del modelo. Si quieres elegirlos tú, añade solo ajustes que aparezcan en las properties de tu modelo, con valores que ese modelo permita. Por ejemplo, si tu modelo enumera duration_seconds y resolution y permite estos valores:

{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5,
  "resolution": "720p"
}

Guarda el archivo en tu carpeta de trabajo:

cat > input.json <<'EOF'
{
  "prompt": "The camera slowly pushes in while rain runs down the window and neon light flickers",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"
}
EOF

Usa comillas rectas normales ("), no comillas tipográficas, y no pongas coma después del último ajuste.

Pide la cotización:

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: …
maxCharge: …
currency: USD
quantity: 5
unit: per_second
expiresAt: 2026-09-17T08:05:00Z

Qué acaba de pasar: SpicyAPI ha comprobado tu entrada contra los ajustes del modelo y ha puesto precio a esta solicitud exacta. No se ha iniciado nada ni se ha cobrado nada. estimatedCost es el importe que se apartará si inicias la tarea ahora, y maxCharge es lo máximo que puede costar. quantity y unit muestran qué pagas, por ejemplo 5 segundos.

Una cotización es válida durante cinco minutos y solo para esta entrada exacta. Cambia la duración o la resolución y vuelve a cotizar para comparar precios. La cotización hace las mismas comprobaciones que iniciar la tarea, así que los problemas aparecen aquí sin costarte nada: un 400 significa que la entrada no coincide con los ajustes del modelo (corrige input.json con lo que viste en el paso 1), y un 40201, que tu saldo no alcanzaría. El paso 7 enumera los demás códigos.

4. Inicia la generación

La clave de idempotencia, en pocas palabras. Es una etiqueta para un video concreto, como un número de pedido. Si se te corta la conexión y no sabes si el video llegó a iniciarse, vuelve a enviar la misma solicitud con la misma etiqueta: SpicyAPI te devuelve la tarea que ya había iniciado en lugar de iniciar, y cobrarte, una segunda. Una etiqueta sirve durante 24 horas con la misma clave de API. Usa una etiqueta nueva para cada video distinto: la misma etiqueta con una entrada diferente se rechaza con 409. Más detalles en Idempotencia.

Qué hacer:

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json

Estimated charge: USD …; maximum charge: USD …. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? … Continue? [y/N]

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
taskId: job_01k3m8x9q2z4v7n5p6r8s0t1w3
state: queued
estimatedCost: …
deadlineAt: 2026-09-17T08:35:00Z

Qué acaba de pasar: SpicyAPI ha aceptado la generación, que ahora es una tarea, y ha apartado estimatedCost de tu saldo. Eso es también lo máximo que puede costar este video. state: queued significa que está esperando su turno. deadlineAt es la hora límite para que termine; si para entonces no ha terminado, acaba como expired y no se cobra nada. deadlineAt no es la fecha en que caducan tus archivos.

Pasar la cotización significa «acéptala solo al precio que me mostraron». Si mientras tanto han cambiado el precio o la entrada, la solicitud se rechaza con 40901 en lugar de apartar un importe distinto. La CLI lo hace por ti.

Si se cortó la conexión y nunca llegaste a ver un ID de tarea, no vuelvas a empezar sin más con una etiqueta nueva: eso crearía un segundo video y te lo cobraría. Repite la solicitud con la misma etiqueta:

• CLI: spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key <the value you copied>. Consulta Retomar una tarea después de que se interrumpiera la espera.
• SDK: vuelve a ejecutar node generate.mjs --yes; reutiliza idempotency-key.txt.
• HTTP: vuelve a ejecutar el bloque «Iniciar el video»; reutiliza idempotency-key.txt.

Si el paso 4 se rechazó, no se ha creado nada ni se ha cobrado nada; el motivo y la solución están en el paso 7.

5. Espera a que el video esté listo

Qué hacer: consulta la tarea hasta que termine. Los videos suelen tardar unos minutos.

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000 --json

{
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "state": "succeeded",
  "output": {
    "assets": [
      {
        "key": "tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4",
        "url": "https://…",
        "expiresAt": "2026-09-17T08:40:00Z",
        "mime": "video/mp4",
        "durationSeconds": 5,
        "width": 1280,
        "height": 720,
        "bytes": 4839211
      }
    ]
  },
  "cost": "…",
  "settled": true
}

Qué acaba de pasar: tu herramienta ha preguntado a SpicyAPI por la tarea cada pocos segundos. Los estados son queued (en espera), running (generándose) y, al final, un estado definitivo: succeeded, failed o expired. Cuando sale bien, el archivo se copia al almacenamiento propio de SpicyAPI, lo que tarda unos segundos más; mientras tanto, el resultado muestra pending: true. cost es definitivo cuando settled está en true.

• Cerrar la terminal o pulsar Ctrl + C no cancela la tarea. Solo detiene la espera. Guarda el ID de la tarea y vuelve a hacer este paso más tarde.
• No consultes más a menudo que cada pocos segundos. Consultar una tarea utiliza la capacidad de lectura de la cuenta, de forma independiente del inicio de tareas; consulta Límites de solicitudes.
• En una aplicación o un servidor, deja que SpicyAPI te avise cuando la tarea termine en lugar de preguntar: consulta Recibe un aviso en lugar de esperar.

6. Descarga y guarda el video

Qué hacer: consigue un enlace de descarga nuevo y guarda el archivo en tu equipo.

spicyapi files download-url job_01k3m8x9q2z4v7n5p6r8s0t1w3

key: tasks/2026/09/17/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4
url: https://…
expiresAt: 2026-09-17T08:52:00Z

curl -L -o my-video.mp4 "PASTE_THE_URL_HERE"

Qué acaba de pasar: cada resultado trae un enlace de descarga directo. El enlace funciona durante unos 20 minutos y no necesita clave de API; no le añadas nunca tu clave. Cuando caduque, vuelve a pedir la tarea (o usa files download-url) para obtener uno nuevo.

7. Cuando algo sale mal

Los problemas son de dos tipos, y cada uno se resuelve de una manera distinta.

Se rechaza una solicitud. Tu comando o tu llamada recibe un error al instante. No se ha creado nada ni se ha cobrado nada. El mensaje explica por qué, y el error lleva un code y un ID de solicitud (req_…) que puedes indicar si contactas con soporte.

La tarea falla. La tarea se aceptó, pero termina como failed o expired en lugar de succeeded. La tarea muestra un errorCode que indica el motivo y un errorMessage que lo explica con más detalle. Las tareas fallidas o vencidas normalmente liberan toda la retención. Algunos rechazos de contenido se cobran al precio aceptado, solo si la página del modelo indica expresamente esta excepción. Consulta settled y cost para conocer el importe final.

Consúltalo:

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

Después decide qué hacer según el errorCode, no según cómo esté redactado el mensaje:

Cualquier otro valor debe tratarse como upstream_failed. La lista completa está en Errores.

Vuelve a ejecutar una tarea fallida. Un reintento crea una tarea nueva con el mismo modelo y la misma entrada, al precio actual del modelo. Cuesta dinero, igual que el paso 4, y conserva la entrada original: si esa entrada usaba una subida que ya ha caducado, vuelve a subir la imagen e inicia una tarea nueva en su lugar.

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait --wait-timeout-ms 1800000

Solo se pueden reintentar las tareas failed y expired. Si quieres otra versión de un video que salió bien, vuelve al paso 3 con una etiqueta nueva. Una vez aceptada, una tarea no se puede cancelar de ninguna manera. Más detalles en Ejecución y reintentos.