Sprite Zenith

Propósito

Gera uma animação de sprite com o pipeline Zenith. É o mesmo recurso da página "Sprite Zenith" do web app e suporta seus três modos:

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: 9 (36 quadros), 25 (100 quadros)

Método e Caminho

POST /public/v1/sprite/zenith

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
frame	integer	Sim para os modos de imagem		Quadros. Valores permitidos: 36, 100. Deve ser omitido em video_restyle (derivado da origem, veja abaixo)
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
is_prompt_enhancement	boolean	Não	true	Aprimoramento do prompt. Refina o que você escreveu para ficar mais adequado à geração de sprites. 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

Regras do Sprite To Sprite (video_restyle)

• Arquivo de origem: uma sprite sheet PNG (envie sprite_grid) ou um GIF (sem sprite_grid). O GIF pode ter no máximo 120 quadros e durar no máximo 10 segundos.
• O número de quadros é derivado da origem, exatamente como no web app: uma origem com mais de 5 segundos produz 100 quadros (25 créditos); caso contrário, 36 quadros (9 créditos). Um GIF usa sua duração real de reprodução; uma sheet PNG com N quadros conta como round(N × 3000 / 36) ms, portanto 61 quadros ou mais usam o nível de 100 quadros.
• text ou reference_image (ou ambos) deve ser informado.
• A extensão do arquivo de origem enviado é determinada pelo seu conteúdo, portanto um GIF é detectado mesmo que o nome do arquivo não tenha extensão.

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"
frame ausente ou não permitido (modos de imagem)	400	"frame should be one of 36, 100"
frame enviado em video_restyle	400	"frame is derived from the source for video_restyle; do not send it"
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/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=image_to_video" \
-F "images=@/path/to/character.png" \
-F "text=running animation cycle" \
-F "frame=36" \
-F "is_pixel=true"

cURL (Referências inicial/final):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-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=turn around" \
-F "frame=100"

cURL (Sprite To Sprite, sheet PNG com grade e imagem de referência):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite_sheet.png" \
-F 'sprite_grid={"columns": 6, "rows": 6}' \
-F "reference_image=@/path/to/new_character.png"

cURL (Sprite To Sprite, GIF com prompt):

curl -X POST "https://api.aetherforgeai.com/public/v1/sprite/zenith" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "mode=video_restyle" \
-F "images=@/path/to/sprite.gif" \
-F "text=a knight in silver armor"