Buat efek V1

Tujuan

Menghasilkan sprite sheet efek secara asinkron dari deskripsi teks. Anda dapat mengunggah gambar referensi secara opsional untuk memandu efek, serta memilih resolusi output dan warna latar belakang sheet. Ini adalah fitur yang sama dengan tab V1 pada halaman "Buat efek" di aplikasi web (aplikasi web membuka tab V2 secara default).

Biaya kredit: 5 (1K), 7 (2K), 10 (4K)

Metode dan Path

POST /public/v1/generate/effect/v1

Autentikasi

Lihat halaman autentikasi. Token Bearer diperlukan.

Header yang Diperlukan:

Authorization: Bearer {your_api_key}

Field Permintaan

Kirim permintaan sebagai multipart/form-data.

Nama Field	Tipe	Wajib	Deskripsi
description	string	Ya	Deskripsi efek. Spasi di awal dan akhir dihapus (trim)
resolution	string	Ya	Resolusi. Nilai yang diizinkan: 1K, 2K, 4K
background_color	string	Ya	Warna latar belakang sheet. Nilai yang diizinkan: white, chroma_green, magenta, light_gray, light_purple, dark_gray
image	file	Tidak	Gambar referensi (opsional) (PNG atau JPEG)

Nilai warna latar belakang

Nilai	Label	Warna
white	Putih	#FFFFFF
chroma_green	Hijau chroma key	#52FF60
magenta	Magenta	#FF4CFF
light_gray	Abu-abu terang	#A6A6A6
light_purple	Ungu terang	#866CFE
dark_gray	Abu-abu gelap	#6A6A6A

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
Gambar bukan file PNG atau JPEG yang valid	400	"Invalid image file"
API key tidak valid	401	"Invalid API key"
Field hilang atau nilai enum tidak dikenal	422	Error validasi

Perilaku Job Async

Endpoint ini membuat job asynchronous. Endpoint akan segera mengembalikan job_id, dan pembuatan efek 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

Alur Status: Pending → Succeed atau Failed

Contoh Permintaan

cURL (tanpa gambar):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/effect/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a glowing fantasy aura" \
-F "resolution=1K" \
-F "background_color=white"

cURL (dengan gambar):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/effect/v1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "description=apply a neon cyberpunk effect" \
-F "resolution=2K" \
-F "background_color=chroma_green" \
-F "image=@/path/to/input.png"