Equipar variación

Propósito

Equipa los objetos de una hoja de objetos sobre una imagen base del personaje y genera las variaciones equipadas. Es la misma función que la página "Equipar variación" de la aplicación web.

Costo en créditos: 5

Método y Ruta

POST /public/v1/image-tune/equip-variation

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.

Nombre del Campo	Tipo	Requerido	Descripción
character_image	file	Sí	Imagen base del personaje (PNG o JPEG)
item_sheet_image	file	Sí	Imagen de la hoja de objetos (PNG o JPEG)
prompt	string	Sí	Prompt que describe cómo equipar los objetos. Se eliminan los espacios en blanco y el prompt no debe estar vacío

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
Alguna de las imágenes no es un archivo PNG o JPEG válido	400	"Invalid image file"
prompt está vacío	400	"prompt must not be empty"
Clave de API inválida	401	"Invalid API key"
Campo faltante	422	Error de validación

Ambas imágenes se validan antes de subir nada, por lo que una solicitud fallida nunca deja subidas parciales.

Comportamiento de Trabajos Asíncronos

Este endpoint crea un trabajo asíncrono. Devuelve inmediatamente un job_id, y la generació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, consulta los resultados en image_urls

Flujo de Estado: Pending → Succeed o Failed

Ejemplo de Solicitud

cURL:

curl -X POST "https://api.aetherforgeai.com/public/v1/image-tune/equip-variation" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "character_image=@/path/to/character.png" \
-F "item_sheet_image=@/path/to/item_sheet.png" \
-F "prompt=equip the iron sword and the leather helmet"