Overlay Karakter V1

Tujuan

Meng-overlay gambar karakter di atas sprite sheet untuk membuat sprite baru. Digunakan saat menggabungkan karakter ke sprite sheet latar belakang.

Metode dan Path

POST /public/v1/sprite/character-overlay/v1

Autentikasi

Lihat halaman Autentikasi. Token Bearer diperlukan.

Header yang Diperlukan:

Authorization: Bearer {your_api_key}

Field Permintaan

Nama Field	Tipe	Wajib	Deskripsi
sprite_sheet	file	Ya	File gambar sprite sheet yang akan menjadi referensi
character_images	file[]	Ya	File gambar karakter yang akan di-overlay. Dapat mengunggah 1 hingga 4 file
rows	string	Ya	String JSON yang berisi informasi baris. Setiap baris harus menyertakan row, title, dan description
resolution	string	Ya	Resolusi output. Nilai yang mungkin: 1K, 2K, 4K
style	string	Tidak	Penentuan gaya (opsional). Nilai yang mungkin: pixel, cartoon, sd, quater_view

Respons

Respons Sukses (200 OK):

{
  "job_id": "uuid-string"
}

Field	Tipe	Deskripsi
job_id	string	Pengidentifikasi unik pekerjaan yang dibuat. Ambil hasil dengan Get Job Status

Aturan Kesalahan / Validasi

Situasi	Status HTTP	Pesan Kesalahan
Invalid image file	400	"Invalid image file"
character_images kurang dari 1 atau lebih dari 4	400	"character_images must contain between 1 and 4 files"
Field character_images tidak disertakan	422	Field required
rows bukan JSON yang valid	400	"rows must be a valid JSON list"
rows bukan list	400	"rows must be a JSON list"
Baris tidak memiliki kunci yang diperlukan	400	"each row must be an object with row, title, description"
row bukan integer	400	"row must be an integer"
title atau description bukan string	400	"title and description must be strings"
Nilai resolution tidak valid	422	Nilai selain 1K, 2K, 4K akan menghasilkan kesalahan validasi
Gagal autentikasi	401	Kunci API tidak valid

Format JSON rows:

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

Perilaku Pekerjaan Asinkron

Endpoint ini membuat pekerjaan asinkron. Ini segera mengembalikan job_id setelah permintaan, dan pekerjaan overlay aktual berlangsung di latar belakang.

Cara Polling:

1. Simpan job_id yang diterima dari respons
2. Lakukan polling ke GET /public/v1/job/{job_id} untuk memeriksa status
3. Ketika status menjadi Succeed, periksa hasil di image_urls

Alur Status: Pending → Succeed atau Failed

Contoh Permintaan

cURL (Karakter Tunggal):

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 (Beberapa Karakter):

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"