Generar efectos V1

Propósito

Genera de forma asíncrona una hoja de sprites de efecto a partir de una descripción de texto. Opcionalmente puedes subir una imagen de referencia para guiar el efecto, y elegir la resolución de salida y el color de fondo de la hoja. Es la misma función que la pestaña V1 de la página "Generar efectos" de la aplicación web (la aplicación web se abre por defecto en la pestaña V2).

Costo en créditos: 5 (1K), 7 (2K), 10 (4K)

Método y Ruta

POST /public/v1/generate/effect/v1

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
description	string	Sí	Descripción del efecto. Se eliminan los espacios en blanco al inicio y al final
resolution	string	Sí	Resolución. Valores permitidos: 1K, 2K, 4K
background_color	string	Sí	Color de fondo de la hoja. Valores permitidos: white, chroma_green, magenta, light_gray, light_purple, dark_gray
image	file	No	Imagen de referencia opcional (PNG o JPEG)

Valores de color de fondo

Valor	Etiqueta	Color
white	Blanco	#FFFFFF
chroma_green	Verde croma	#52FF60
magenta	Magenta	#FF4CFF
light_gray	Gris claro	#A6A6A6
light_purple	Púrpura claro	#866CFE
dark_gray	Gris oscuro	#6A6A6A

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
La imagen no es un archivo PNG o JPEG válido	400	"Invalid image file"
Clave de API inválida	401	"Invalid API key"
Campo faltante o valor de enumeración desconocido	422	Error de validación

Comportamiento de Trabajos Asíncronos

Este endpoint crea un trabajo asíncrono. Devuelve inmediatamente un job_id, y la generación real del efecto 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

Flujo de Estado: Pending → Succeed o Failed

Ejemplo de Solicitud

cURL (sin imagen):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/effect/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a glowing fantasy aura" \
-F "resolution=1K" \
-F "background_color=white"

cURL (con imagen):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/effect/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a neon cyberpunk effect" \
-F "resolution=2K" \
-F "background_color=chroma_green" \
-F "image=@/path/to/input.png"