Quickstart
Dari API key sampai gambar jadi, dalam empat permintaan.
Halaman ini menelusuri satu proses generasi utuh. Semua permintaan memakai key yang sama, dikirim
lewat header x-mager-api-key.
1. Dapatkan API key
Buka dashboard Mager, ajukan akun developer, lalu buat key setelah akun disetujui. Nilai asli key hanya ditampilkan sekali, saat dibuat. Simpan di tempat yang bisa dibaca aplikasi Anda — nilainya tidak bisa diambil ulang.
Bentuk key-nya seperti ini:
mager_sk_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f4cPerlakukan seperti password. Ini kredensial sisi server; jangan pernah dikirim ke browser atau aplikasi mobile. Lihat Authentication untuk scope dan rotasi key.
2. Cari model
curl https://api.mageran.ai/api/v1/models \
--header 'x-mager-api-key: YOUR_API_KEY'Setiap entri punya slug model dan input_schema yang menjelaskan field yang diterima model
tersebut:
{
"status": 200,
"message": "Success",
"data": [
{
"model": "image-generator",
"title": "Image Generator",
"capability": "IMAGE_GENERATION",
"default_output_count": 1,
"input_schema": {
"type": "object",
"properties": {
"prompt": { "type": "string" },
"aspectRatio": { "type": "string", "enum": ["1:1", "9:16", "16:9"] }
},
"required": ["prompt"]
},
"model_tiers": ["lite", "max"]
}
]
}Baca input_schema alih-alih menuliskan field secara hardcode. Itu kontrak untuk langkah 3, dan
isinya berbeda per model.
3. Buat task
curl https://api.mageran.ai/api/v1/generation-tasks \
--request POST \
--header 'x-mager-api-key: YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"model": "image-generator",
"model_tier": "max",
"input": {
"prompt": "Studio product photo of a cold matcha latte bottle",
"aspectRatio": "1:1"
},
"output_count": 1
}'Response langsung kembali dengan task_id dan status queued atau running. Proses generasi
berjalan di latar belakang.
{
"status": 201,
"message": "Success",
"data": {
"task_id": "cmagr01hxyz123",
"status": "running",
"model": "image-generator",
"billing": { "base_moods": 10, "charged_moods": 15, "extra_moods_charged": 5 },
"result": []
}
}4. Tunggu hasilnya
Lakukan polling sampai status task menjadi finished atau failed:
curl https://api.mageran.ai/api/v1/generation-tasks/cmagr01hxyz123 \
--header 'x-mager-api-key: YOUR_API_KEY'{
"status": 200,
"data": {
"task_id": "cmagr01hxyz123",
"status": "finished",
"completed_at": "2026-07-03T06:01:00.000Z",
"result": [
{
"id": "result_01hxyz",
"status": "SUCCESS",
"file_url": "https://cdn.example.com/generated-image.png",
"file_type": "image/png"
}
]
}
}Polling setiap beberapa detik, bukan setiap beberapa ratus milidetik — polling ikut dihitung dalam rate limit Anda.
Lebih baik lagi: kirim callback_url saat membuat task, dan Mager yang akan menghubungi Anda. Lihat
Webhooks.