Sprite Zenith

Propósito

Genera una animación de sprite con el pipeline Zenith. Es la misma función que la página "Sprite Zenith" de la aplicación web y admite sus tres modos:

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: 9 (36 fotogramas), 25 (100 fotogramas)

Método y Ruta

POST /public/v1/sprite/zenith

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
frame	integer	Sí para los modos de imagen		Fotogramas. Valores permitidos: 36, 100. Debe omitirse en video_restyle (se deriva del origen, ver abajo)
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
is_prompt_enhancement	boolean	No	true	Mejora del prompt. Refina lo que escribes para que sea más adecuado para generar sprites. 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

Reglas de Sprite To Sprite (video_restyle)

• Archivo de origen: una hoja de sprites PNG (envía sprite_grid) o un GIF (sin sprite_grid). El GIF puede tener como máximo 120 fotogramas y durar como máximo 10 segundos.
• El número de fotogramas se deriva del origen, exactamente igual que en la aplicación web: un origen de más de 5 segundos produce 100 fotogramas (25 créditos); de lo contrario, 36 fotogramas (9 créditos). Un GIF usa su longitud real de reproducción; una hoja PNG con N fotogramas cuenta como round(N × 3000 / 36) ms, por lo que 61 fotogramas o más usan el nivel de 100 fotogramas.
• Debe enviarse text o reference_image (o ambos).
• La extensión del archivo de origen subido se obtiene de su contenido, por lo que un GIF se detecta aunque el nombre del archivo no tenga extensión.

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"
frame faltante o no permitido (modos de imagen)	400	"frame should be one of 36, 100"
frame enviado en video_restyle	400	"frame is derived from the source for video_restyle; do not send it"
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/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=image_to_video" \
-F "images=@/path/to/character.png" \
-F "text=running animation cycle" \
-F "frame=36" \
-F "is_pixel=true"

cURL (Referencias inicial/final):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-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=turn around" \
-F "frame=100"

cURL (Sprite To Sprite, hoja PNG con cuadrícula e imagen de referencia):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite_sheet.png" \
-F 'sprite_grid={"columns": 6, "rows": 6}' \
-F "reference_image=@/path/to/new_character.png"

cURL (Sprite To Sprite, GIF con prompt):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite.gif" \
-F "text=a knight in silver armor"