Sobreposição de Personagem V1

Propósito

Sobrepõe uma imagem de personagem em um sprite sheet para criar um novo sprite. Usado para compor um personagem em um sprite sheet de fundo.

Método e Caminho

POST /public/v1/sprite/character-overlay/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

Nome do Campo	Tipo	Obrigatório	Descrição
sprite_sheet	file	Sim	Arquivo de imagem do sprite sheet que servirá como referência
character_images	file[]	Sim	Arquivos de imagens de personagens para sobrepor. De 1 a 4 arquivos podem ser enviados
rows	string	Sim	String JSON contendo informações das linhas. Cada linha deve incluir row, title e description
resolution	string	Sim	Resolução de saída. Valores possíveis: 1K, 2K, 4K
style	string	Não	Especificação de estilo (opcional). Valores possíveis: pixel, cartoon, sd, quater_view

Resposta

Resposta de Sucesso (200 OK):

{
  "job_id": "uuid-string"
}

Campo	Tipo	Descrição
job_id	string	Identificador único do job criado. Consulte o resultado em Get Job Status

Regras de Erro / Validação

Situação	Status HTTP	Mensagem de Erro
Invalid image file	400	"Invalid image file"
character_images com menos de 1 ou mais de 4	400	"character_images must contain between 1 and 4 files"
Campo character_images ausente	422	Field required
rows não é um JSON válido	400	"rows must be a valid JSON list"
rows não é uma lista	400	"rows must be a JSON list"
Chaves obrigatórias ausentes na linha	400	"each row must be an object with row, title, description"
row não é um inteiro	400	"row must be an integer"
title ou description não são strings	400	"title and description must be strings"
Valor de resolution inválido	422	Valores diferentes de 1K, 2K, 4K resultam em erro de validação
Falha de autenticação	401	Chave de API inválida

Formato JSON de rows:

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

Comportamento do Job Assíncrono

Este endpoint cria um job assíncrono. Ele retorna imediatamente um job_id, e o trabalho real de overlay 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 for Succeed, verifique o resultado em image_urls

Fluxo de Status: Pending → Succeed ou Failed

Exemplo de Requisição

cURL (personagem ú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últiplos personagens):

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"