Equipar variação

Propósito

Equipa itens de uma folha de itens em uma imagem base de personagem e gera as variações equipadas. É o mesmo recurso da página "Equipar variação" do web app.

Custo em créditos: 5

Método e Caminho

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

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
character_image	file	Sim	Imagem base do personagem (PNG ou JPEG)
item_sheet_image	file	Sim	Imagem da folha de itens (PNG ou JPEG)
prompt	string	Sim	Prompt descrevendo como equipar os itens. Espaços em branco são removidos e o prompt não pode estar vazio

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
Uma das imagens não é um arquivo PNG ou JPEG válido	400	"Invalid image file"
prompt está vazio	400	"prompt must not be empty"
Chave de API inválida	401	"Invalid API key"
Campo ausente	422	Erro de validação

As duas imagens são validadas antes de qualquer upload, portanto uma requisição com falha nunca deixa uploads parciais para trás.

Comportamento do Job Assíncrono

Este endpoint cria um job assíncrono. Ele retorna imediatamente um job_id, e a geração é executada 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:

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"