01
Una relación de aspecto que no encaja sale cara en silencio
Si la referencia es 1:1 y pides un clip 16:9, el endpoint tiene que enmarcar, recortar o estirar. Ajusta la referencia al aspect_ratio o la resolution que vas a pedir antes de enviar.
Guía de integración
Anima un fijo que ya te convence.
Imagen a vídeo elimina la variable más difícil —qué aspecto tiene la escena— y la sustituye por otra más estrecha: cómo debe moverse. El fotograma de referencia hace casi todo el trabajo, por eso la indicación no rescata una referencia floja.
El reto
El fotograma de referencia decide casi todo el resultado
Los endpoints de movimiento heredan todo del primer fotograma: encuadre, luz, relación de aspecto, artefactos. Una referencia blanda o mal recortada produce un clip blando y mal recortado, y se paga a tarifa de vídeo.
02
Algunos endpoints también aceptan un fotograma final
Donde se declara last_image_url, dar ambos extremos define principio y final en lugar de una deriva abierta. Donde no se declara, enviarlo es un 400.
03
Los campos de movimiento existen solo donde están declarados
movement_amplitude, camera_fixed, fps y duration_seconds aparecen según el endpoint, y el esquema marca cuáles mueven la tarifa. No hay debajo un vocabulario de movimiento compartido.
El enfoque
Fija primero el fotograma y paga el movimiento una sola vez
Haz el trabajo de imagen fija en un endpoint de imagen, donde una iteración cuesta céntimos, fija el fotograma y solo entonces paga el movimiento. Pasar una subida spicy:// confirmada mantiene la referencia idéntica byte a byte entre intentos, así que una repetición parte exactamente de los mismos píxeles.
El cuerpo es una llamada de creación con campo de imagen. El seguimiento es idéntico al de cualquier otra tarea de medios.
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/image-to-video",
"input": {
"prompt": "Slow push-in, fabric moving in a light breeze",
"image_url": "https://example.com/reference.png",
"duration_seconds": 5,
"resolution": "720p"
},
"callBackUrl": "https://example.com/hooks/spicyapi"
}202 Accepted
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}Contrato
Lo que conviene fijar desde el principio
| Campo o cabecera | Valor o límite |
|---|---|
| image_url · last_image_url | declared per endpoint |
| POST /api/v1/jobs/retry | new task · source record untouched |
| state | queued · running · succeeded · failed · expired |
| audio / video upload | ≤ 100 MiB · ≤ 600 s |
Desliza horizontalmente para ver todas las columnas.
Integración
De la primera llamada a producción
- 01Produce o sube el fotograma de referencia con la relación de aspecto que vas a renderizar.
- 02Lee en el esquema image_url, duration_seconds, resolution y los campos de movimiento declarados.
- 03Estima, envía con Idempotency-Key y URL de devolución, y guarda el taskId junto a la referencia.
- 04Al llegar la devolución terminal, descarga output.assets y conserva la referencia junto al clip para poder repetir.
Encaje
Cuándo este camino es el adecuado
Elígelo si
- La dirección de arte ya está fijada en un fijo y quieres movimiento sin volver a tirar los dados de la escena.
- El mismo personaje o producto debe verse idéntico en cada clip.
Busca otra vía si
- La escena todavía no existe. Iterar sobre fijos cuesta un orden de magnitud menos que iterar sobre clips.
- Necesitas continuidad a lo largo de muchos planos. Estos endpoints devuelven clips cortos, un plano cada vez.
Comprobaciones
Lo que puedes verificar tú mismo
Las referencias se comportan igual en todas partes
URL HTTPS, subidas spicy:// confirmadas y data URI incrustadas funcionan igual en endpoints de imagen y de vídeo, con los mismos límites y las mismas comprobaciones de admisión.
Un reintento crea una tarea nueva y nunca toca la anterior
POST /api/v1/jobs/retry construye una tarea a partir de otra fallida o caducada y reevalúa esquema, precio, permisos y disponibilidad. El registro original queda intacto.
Un solo autómata de estados para toda la integración
queued, running, succeeded, failed, expired. Las mismas cinco palabras describen cada endpoint de medios, así que la lógica de transición se escribe una vez.
Antes del lanzamiento
Comportamientos de la plataforma que conviene confirmar
- Ajusta la relación de la referencia a la salida antes del lanzamiento, no en los tiques de soporte.
- Mantén la referencia accesible durante toda la vida de la tarea, no solo en el momento del envío.
- Da a los reintentos su propio ámbito de idempotencia; un reintento es una tarea nueva, no una repetición.
- Incluye las tarifas de vídeo en el tope diario obligatorio de la clave.
Preguntas frecuentes
Lo que más se pregunta en esta página
Es tu decisión y tu responsabilidad legal. La plataforma no inspecciona la identidad de las subidas, y las condiciones sitúan consentimiento y derechos en el cliente.
El primer fotograma ancla el resultado, pero cada endpoint lo sostiene con distinto rigor. Cada página de modelo describe su comportamiento y los controles disponibles.
Sube duration_seconds dentro de lo que permita el endpoint, o genera planos por separado y móntalos. La duración está acotada por endpoint y se cobra por segundo.
Recibes un registro terminal con un errorCode estable, la reserva se libera íntegra y un reintento puede crear una tarea nueva desde la misma fuente sin tocar el registro original.
Modelos
Modelos que puedes llamar para esto
Cada enlace abre la página de esa familia de modelos: entradas, límites, política de contenido y el precio actual por unidad.
AlibabaWan 3.0Imagen a videoPolítica de contenido: Sin censuraByteDanceSeedance 2.5Referencia a videoPolítica de contenido: Sin censuraKlingKling 3.0Animación de personajesPolítica de contenido: Con filtroByteDanceSeedance 2.5 SpicyImagen a videoPolítica de contenido: Sin censuraAlibabaWan 3.0 PrimeReferencia a videoPolítica de contenido: Sin censuraKlingKling 2.6Animación de personajesPolítica de contenido: Con filtro
Siguiente paso
Probar un endpoint de imagen a vídeo
Convierte una imagen de referencia en un clip. Qué hacen la calidad del primer fotograma, la relación de aspecto, los campos de movimiento y la duración.