Sprite Pulsar

Propósito

Genera una animación de sprite de 36 fotogramas con el pipeline Pulsar. Es la misma función que la página "Sprite Pulsar" de la aplicación web. Usa las mismas entradas y modos que Sprite Zenith, pero la duración está fijada en 36 fotogramas y no existe la opción de mejora del prompt.

mode	Pestaña web	Entrada
image_to_video	Imagen única	Una imagen
first_last_frame	Referencias inicial/final	Dos imágenes: el fotograma inicial y la imagen de referencia final, en ese orden
video_restyle	Sprite To Sprite	Un sprite existente (hoja de sprites PNG + cuadrícula, o GIF) y una imagen de referencia opcional

Costo en créditos: 3 (image_to_video, first_last_frame), 4 (video_restyle)

Método y Ruta

POST /public/v1/sprite/pulsar

Autenticación

Consulta la página de autenticación. Se requiere un token Bearer.

Encabezados Requeridos:

Authorization: Bearer {your_api_key}

Campos de Solicitud

Envía la solicitud como multipart/form-data. Repite el campo images una vez por archivo.

Nombre del Campo	Tipo	Requerido	Por defecto	Descripción
mode	string	Sí		Valores permitidos: image_to_video, first_last_frame, video_restyle
images	file[]	Sí		image_to_video: exactamente 1 PNG/JPEG. first_last_frame: exactamente 2 PNG/JPEG (inicial, final). video_restyle: exactamente 1 origen, hoja de sprites PNG o GIF
text	string	Sí, excepto con una imagen de referencia	""	Prompt que describe el movimiento. Se eliminan los espacios en blanco. En video_restyle puede estar vacío solo cuando se envía reference_image
is_pixel	boolean	No	false	Pixel art. Activa esta opción si la imagen adjunta está basada en pixel art. Se ignora (se fuerza a false) en video_restyle
reference_image	file	No (solo video_restyle)		Imagen de referencia (opcional). Solo PNG. El sujeto del sprite de origen se reemplaza con esta imagen
sprite_grid	string	video_restyle con una hoja PNG		Objeto JSON que describe cómo se corta la hoja PNG, p. ej. {"columns": 6, "rows": 6}. Cada valor entre 1 y 32, como máximo 120 fotogramas. No permitido con un origen GIF

Las reglas del origen de Sprite To Sprite (video_restyle) son las mismas que en Sprite Zenith: hoja PNG + sprite_grid, o un GIF de como máximo 120 fotogramas y 10 segundos. No existe el campo frame; la salida siempre es de 36 fotogramas.

Respuesta

Respuesta Exitosa (200 OK):

{
  "job_id": "uuid-string"
}

Campo	Tipo	Descripción
job_id	string	Identificador único del trabajo creado. Consulta los resultados con Get Job Status

Reglas de Error / Validación

Situación	Estado HTTP	Mensaje de Error
Un archivo no es una imagen válida o tiene un formato no permitido	400	"Invalid image file"
Número de imágenes incorrecto para el modo	400	"image_to_video requires exactly one image" / "first_last_frame requires exactly two images (start, end)" / "video_restyle requires exactly one source image (PNG sprite sheet or GIF)"
text vacío (modos de imagen)	400	"text must not be empty"
text vacío y sin imagen de referencia (video_restyle)	400	"video_restyle requires text when no reference_image is given"
reference_image o sprite_grid enviados fuera de video_restyle	400	"reference_image is only supported for video_restyle" / "sprite_grid is only supported for video_restyle"
Hoja PNG sin sprite_grid	400	"sprite_grid is required for a PNG sprite sheet"
GIF con sprite_grid	400	"sprite_grid is not allowed for a GIF source"
sprite_grid mal formado o fuera de rango	400	sprite_grid must be a JSON object like {"columns": 6, "rows": 6} (1-32 each, at most 120 frames)
El GIF tiene más de 120 fotogramas	400	"GIF must have at most 120 frames"
El GIF dura más de 10 segundos	400	"GIF must be at most 10 seconds long"
Clave de API inválida	401	"Invalid API key"
Campo faltante o mode desconocido	422	Error de validación

Toda la validación se ejecuta antes de subir cualquier archivo.

Comportamiento de Trabajos Asíncronos

Este endpoint crea un trabajo asíncrono. Devuelve inmediatamente un job_id, y la generación real del sprite ocurre en segundo plano.

Método de Polling:

1. Guarda el job_id recibido en la respuesta
2. Haz polling a GET /public/v1/job/{job_id} para verificar el estado
3. Cuando el estado sea Succeed, consulta los resultados en image_urls (hoja de sprites y GIF)

Flujo de Estado: Pending → Succeed o Failed

Ejemplo de Solicitud

cURL (Imagen única):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=image_to_video" \
-F "images=@/path/to/character.png" \
-F "text=idle breathing" \
-F "is_pixel=true"

cURL (Referencias inicial/final):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=first_last_frame" \
-F "images=@/path/to/start.png" \
-F "images=@/path/to/end.png" \
-F "text=draw the sword"

cURL (Sprite To Sprite, GIF con imagen de referencia):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite.gif" \
-F "reference_image=@/path/to/new_character.png"