Superposición de Personaje V1

Propósito

Superpone imágenes de personajes sobre un sprite sheet para crear nuevos sprites. Se utiliza al componer personajes sobre un sprite sheet de fondo.

Método y Ruta

POST /public/v1/sprite/character-overlay/v1

Autenticación

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

Encabezados Requeridos:

Authorization: Bearer {your_api_key}

Campos de la Solicitud

Nombre del Campo	Tipo	Requerido	Descripción
sprite_sheet	file	Sí	Archivo de imagen del sprite sheet que se usará como referencia
character_images	file[]	Sí	Archivos de imagen de personajes para superponer. Se pueden subir de 1 a 4 archivos
rows	string	Sí	Cadena JSON que contiene información de filas. Cada fila debe incluir row, title y description
resolution	string	Sí	Resolución de salida. Valores posibles: 1K, 2K, 4K
style	string	No	Especificación de estilo (opcional). Valores posibles: pixel, cartoon, sd, quater_view

Respuesta

Respuesta Exitosa (200 OK):

{
  "job_id": "uuid-string"
}

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

Reglas de Error / Validación

Situación	Estado HTTP	Mensaje de Error
Invalid image file	400	"Invalid image file"
character_images menor a 1 o mayor a 4	400	"character_images must contain between 1 and 4 files"
Falta el campo character_images	422	Field required
rows no es un JSON válido	400	"rows must be a valid JSON list"
rows no es una lista	400	"rows must be a JSON list"
Fila sin claves requeridas	400	"each row must be an object with row, title, description"
row no es un entero	400	"row must be an integer"
title o description no son cadenas	400	"title and description must be strings"
Valor de resolution inválido	422	Valores distintos a 1K, 2K, 4K resultarán en error de validación
Fallo de autenticación	401	API key inválida

Formato JSON de rows:

[
  {
    "row": 1,
    "title": "Idle",
    "description": "Character standing still"
  },
  {
    "row": 2,
    "title": "Walk",
    "description": "Character walking animation"
  }
]

Comportamiento del Trabajo Asíncrono

Este endpoint crea un trabajo asíncrono. Devuelve inmediatamente un job_id, y el trabajo real de superposición se ejecuta 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, verifica los resultados en image_urls

Flujo de Estados: Pending → Succeed o Failed

Ejemplo de Solicitud

cURL (Personaje Único):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/character-overlay/v1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "sprite_sheet=@/path/to/background_sprite.png" \
  -F "character_images=@/path/to/character.png" \
  -F 'rows=[{"row":1,"title":"Idle","description":"Standing"},{"row":2,"title":"Walk","description":"Walking"}]' \
  -F "resolution=2K"

cURL (Múltiples Personajes):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/character-overlay/v1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "sprite_sheet=@/path/to/background_sprite.png" \
  -F "character_images=@/path/to/char1.png" \
  -F "character_images=@/path/to/char2.png" \
  -F "character_images=@/path/to/char3.png" \
  -F 'rows=[{"row":1,"title":"Scene1","description":"First scene"},{"row":2,"title":"Scene2","description":"Second scene"}]' \
  -F "resolution=2K" \
  -F "style=pixel"