Sprite Pulsar

Propósito

Gera uma animação de sprite de 36 quadros com o pipeline Pulsar. É o mesmo recurso da página "Sprite Pulsar" do web app. Usa as mesmas entradas e modos do Sprite Zenith, mas a duração é fixa em 36 quadros e não há opção de aprimoramento do prompt.

mode	Aba do web app	Entrada
image_to_video	Imagem única	Uma imagem
first_last_frame	Referências inicial/final	Duas imagens: o quadro inicial e a imagem de referência final, nessa ordem
video_restyle	Sprite To Sprite	Um sprite existente (sprite sheet PNG + grade, ou GIF) e uma imagem de referência opcional

Custo em créditos: 3 (image_to_video, first_last_frame), 4 (video_restyle)

Método e Caminho

POST /public/v1/sprite/pulsar

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. Repita o campo images uma vez para cada arquivo.

Nome do Campo	Tipo	Obrigatório	Padrão	Descrição
mode	string	Sim		Valores permitidos: image_to_video, first_last_frame, video_restyle
images	file[]	Sim		image_to_video: exatamente 1 PNG/JPEG. first_last_frame: exatamente 2 PNG/JPEG (inicial, final). video_restyle: exatamente 1 origem, sprite sheet PNG ou GIF
text	string	Sim, exceto com imagem de referência	""	Prompt descrevendo o movimento. Espaços em branco são removidos. Em video_restyle, pode estar vazio apenas quando reference_image é informado
is_pixel	boolean	Não	false	Pixel art. Ative esta opção se a imagem anexada for baseada em pixel art. Ignorado (forçado para false) em video_restyle
reference_image	file	Não (apenas video_restyle)		Imagem de referência (opcional). Apenas PNG. O sujeito do sprite de origem é substituído por esta imagem
sprite_grid	string	video_restyle com sheet PNG		Objeto JSON que descreve como a sheet PNG é recortada, ex.: {"columns": 6, "rows": 6}. Cada valor de 1 a 32, no máximo 120 quadros. Não permitido com origem GIF

As regras de origem do Sprite To Sprite (video_restyle) são as mesmas do Sprite Zenith: sheet PNG + sprite_grid, ou um GIF com no máximo 120 quadros e 10 segundos. Não há campo frame; a saída tem sempre 36 quadros.

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
Um arquivo não é uma imagem válida ou tem formato não permitido	400	"Invalid image file"
Número de imagens incorreto para o mode	400	"image_to_video requires exactly one image" / "first_last_frame requires exactly two images (start, end)" / "video_restyle requires exactly one source image (PNG sprite sheet or GIF)"
text vazio (modos de imagem)	400	"text must not be empty"
text vazio e sem imagem de referência (video_restyle)	400	"video_restyle requires text when no reference_image is given"
reference_image ou sprite_grid enviado fora de video_restyle	400	"reference_image is only supported for video_restyle" / "sprite_grid is only supported for video_restyle"
Sheet PNG sem sprite_grid	400	"sprite_grid is required for a PNG sprite sheet"
GIF com sprite_grid	400	"sprite_grid is not allowed for a GIF source"
sprite_grid malformado ou fora do intervalo	400	sprite_grid must be a JSON object like {"columns": 6, "rows": 6} (1-32 each, at most 120 frames)
GIF com mais de 120 quadros	400	"GIF must have at most 120 frames"
GIF com mais de 10 segundos	400	"GIF must be at most 10 seconds long"
Chave de API inválida	401	"Invalid API key"
Campo ausente ou mode desconhecido	422	Erro de validação

Toda a validação é executada antes do upload de qualquer arquivo.

Comportamento do Job Assíncrono

Este endpoint cria um job assíncrono. Ele retorna imediatamente um job_id, e a geração real do sprite 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 (sprite sheet e GIF)

Fluxo de Status: Pending → Succeed ou Failed

Exemplo de Requisição

cURL (Imagem única):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=image_to_video" \
-F "images=@/path/to/character.png" \
-F "text=idle breathing" \
-F "is_pixel=true"

cURL (Referências inicial/final):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=first_last_frame" \
-F "images=@/path/to/start.png" \
-F "images=@/path/to/end.png" \
-F "text=draw the sword"

cURL (Sprite To Sprite, GIF com imagem de referência):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/pulsar" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite.gif" \
-F "reference_image=@/path/to/new_character.png"