Gerar efeitos V1

Propósito

Gera de forma assíncrona uma sprite sheet de efeito a partir de uma descrição em texto. Opcionalmente, você pode enviar uma imagem de referência para guiar o efeito e escolher a resolução de saída e a cor de fundo da sheet. É o mesmo recurso da aba V1 da página "Gerar efeitos" do web app (o web app abre na aba V2 por padrão).

Custo em créditos: 5 (1K), 7 (2K), 10 (4K)

Método e Caminho

POST /public/v1/generate/effect/v1

Autenticação

Consulte a página de Autenticação. É necessário um token Bearer.

Cabeçalhos Obrigatórios:

Authorization: Bearer {your_api_key}

Campos da Requisição

Envie a requisição como multipart/form-data.

Nome do Campo	Tipo	Obrigatório	Descrição
description	string	Sim	Descrição do efeito. Espaços em branco no início e no fim são removidos
resolution	string	Sim	Resolução. Valores permitidos: 1K, 2K, 4K
background_color	string	Sim	Cor de fundo da sheet. Valores permitidos: white, chroma_green, magenta, light_gray, light_purple, dark_gray
image	file	Não	Imagem de referência opcional (PNG ou JPEG)

Valores de cor de fundo

Valor	Rótulo	Cor
white	Branco	#FFFFFF
chroma_green	Verde chroma key	#52FF60
magenta	Magenta	#FF4CFF
light_gray	Cinza claro	#A6A6A6
light_purple	Roxo claro	#866CFE
dark_gray	Cinza escuro	#6A6A6A

Resposta

Resposta de Sucesso (200 OK):

{
  "job_id": "uuid-string"
}

Campo	Tipo	Descrição
job_id	string	Identificador único do job criado. Use Obter Status do Job para consultar os resultados

Regras de Erro / Validação

Situação	Status HTTP	Mensagem de Erro
A imagem não é um arquivo PNG ou JPEG válido	400	"Invalid image file"
Chave de API inválida	401	"Invalid API key"
Campo ausente ou valor de enum desconhecido	422	Erro de validação

Comportamento do Job Assíncrono

Este endpoint cria um job assíncrono. Ele retorna imediatamente um job_id, e a geração real do efeito ocorre em segundo plano.

Método de Polling:

1. Salve o job_id recebido na resposta
2. Faça polling em GET /public/v1/job/{job_id} para verificar o status
3. Quando o status se tornar Succeed, verifique os resultados em image_urls

Fluxo de Status: Pending → Succeed ou Failed

Exemplo de Requisição

cURL (sem imagem):

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 (com imagem):

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"