Sprite Zenith

Tujuan

Menghasilkan animasi sprite dengan pipeline Zenith. Ini adalah fitur yang sama dengan halaman "Sprite Zenith" di aplikasi web dan mendukung tiga modenya:

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

Metode dan Path

POST /public/v1/sprite/zenith

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
frame	integer	Ya untuk mode gambar		Frame. Nilai yang diizinkan: 36, 100. Harus dihilangkan pada video_restyle (diturunkan dari sumber, lihat di bawah)
is_pixel	boolean	Tidak	false	Pixel art. Aktifkan ini jika gambar yang dilampirkan berbasis pixel art. Diabaikan (dipaksa false) pada video_restyle
is_prompt_enhancement	boolean	Tidak	true	Penyempurnaan prompt. Menyempurnakan input Anda agar lebih sesuai untuk pembuatan sprite. 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 Sprite To Sprite (video_restyle)

• File sumber: sprite sheet PNG (kirim sprite_grid) atau GIF (tanpa sprite_grid). GIF boleh memiliki maksimal 120 frame dan berdurasi maksimal 10 detik.
• Jumlah frame diturunkan dari sumber, persis seperti di aplikasi web: sumber yang lebih panjang dari 5 detik menghasilkan 100 frame (25 kredit), selain itu 36 frame (9 kredit). GIF menggunakan panjang pemutaran sebenarnya; sheet PNG dengan N frame dihitung sebagai round(N × 3000 / 36) ms, sehingga 61 frame atau lebih menggunakan tingkat 100 frame.
• text atau reference_image (atau keduanya) harus diberikan.
• Ekstensi file dari sumber yang diunggah diambil dari isinya, sehingga GIF tetap terdeteksi meskipun nama file tidak memiliki ekstensi.

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"
frame hilang atau tidak diizinkan (mode gambar)	400	"frame should be one of 36, 100"
frame dikirim pada video_restyle	400	"frame is derived from the source for video_restyle; do not send it"
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/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 (Referensi awal/akhir):

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

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 dengan 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"