Sprite Pulsar

Tujuan

Menghasilkan animasi sprite 36 frame dengan pipeline Pulsar. Ini adalah fitur yang sama dengan halaman "Sprite Pulsar" di aplikasi web. Endpoint ini menggunakan input dan mode yang sama dengan Sprite Zenith, tetapi panjangnya tetap 36 frame dan tidak ada opsi penyempurnaan prompt.

mode	Tab web	Input
image_to_video	Gambar tunggal	Satu gambar
first_last_frame	Referensi awal/akhir	Dua gambar: frame awal dan gambar referensi akhir, secara berurutan
video_restyle	Sprite To Sprite	Satu sprite yang sudah ada (sprite sheet PNG + grid, atau GIF) dan gambar referensi opsional

Biaya kredit: 3 (image_to_video, first_last_frame), 4 (video_restyle)

Metode dan Path

POST /public/v1/sprite/pulsar

Autentikasi

Lihat halaman autentikasi. Token Bearer diperlukan.

Header yang Diperlukan:

Authorization: Bearer {your_api_key}

Field Permintaan

Kirim permintaan sebagai multipart/form-data. Ulangi field images satu kali untuk setiap file.

Nama Field	Tipe	Wajib	Default	Deskripsi
mode	string	Ya		Nilai yang diizinkan: image_to_video, first_last_frame, video_restyle
images	file[]	Ya		image_to_video: tepat 1 PNG/JPEG. first_last_frame: tepat 2 PNG/JPEG (awal, akhir). video_restyle: tepat 1 sumber, sprite sheet PNG atau GIF
text	string	Ya, kecuali dengan gambar referensi	""	Prompt yang menjelaskan gerakan. Spasi dihapus (trim). Pada video_restyle boleh kosong hanya jika reference_image diberikan
is_pixel	boolean	Tidak	false	Pixel art. Aktifkan ini jika gambar yang dilampirkan berbasis pixel art. Diabaikan (dipaksa false) pada video_restyle
reference_image	file	Tidak (hanya video_restyle)		Gambar referensi (opsional). Hanya PNG. Subjek sprite sumber diganti dengan gambar ini
sprite_grid	string	video_restyle dengan sheet PNG		Objek JSON yang menjelaskan cara sheet PNG dipotong, mis. {"columns": 6, "rows": 6}. Setiap nilai 1–32, maksimal 120 frame. Tidak diizinkan dengan sumber GIF

Aturan sumber Sprite To Sprite (video_restyle) sama dengan Sprite Zenith: sheet PNG + sprite_grid, atau GIF dengan maksimal 120 frame dan 10 detik. Tidak ada field frame; output selalu 36 frame.

Respons

Respons Berhasil (200 OK):

{
  "job_id": "uuid-string"
}

Field	Tipe	Deskripsi
job_id	string	Pengidentifikasi unik untuk job yang dibuat. Gunakan Get Job Status untuk melihat hasil

Aturan Error / Validasi

Kondisi	Status HTTP	Pesan Error
File bukan gambar yang valid atau memiliki format yang tidak diizinkan	400	"Invalid image file"
Jumlah gambar salah untuk mode tersebut	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 kosong (mode gambar)	400	"text must not be empty"
text kosong dan tidak ada gambar referensi (video_restyle)	400	"video_restyle requires text when no reference_image is given"
reference_image atau sprite_grid dikirim di luar video_restyle	400	"reference_image is only supported for video_restyle" / "sprite_grid is only supported for video_restyle"
Sheet PNG tanpa sprite_grid	400	"sprite_grid is required for a PNG sprite sheet"
GIF dengan sprite_grid	400	"sprite_grid is not allowed for a GIF source"
sprite_grid salah format atau di luar rentang	400	sprite_grid must be a JSON object like {"columns": 6, "rows": 6} (1-32 each, at most 120 frames)
GIF memiliki lebih dari 120 frame	400	"GIF must have at most 120 frames"
GIF lebih panjang dari 10 detik	400	"GIF must be at most 10 seconds long"
API key tidak valid	401	"Invalid API key"
Field hilang atau mode tidak dikenal	422	Error validasi

Semua validasi dijalankan sebelum file apa pun diunggah.

Perilaku Job Async

Endpoint ini membuat job asynchronous. Endpoint akan segera mengembalikan job_id, dan pembuatan sprite sebenarnya terjadi di latar belakang.

Metode Polling:

1. Simpan job_id yang diterima dari respons
2. Poll GET /public/v1/job/{job_id} untuk memeriksa status
3. Saat status menjadi Succeed, lihat hasil pada image_urls (sprite sheet dan GIF)

Alur Status: Pending → Succeed atau Failed

Contoh Permintaan

cURL (Gambar tunggal):

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 (Referensi awal/akhir):

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 dengan gambar referensi):

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"