Models and templates

Dua endpoint menentukan apa yang bisa Anda kirim ke POST /generation-tasks.

Model

GET /models mengembalikan semua yang bisa dihasilkan Mager. Setiap entri terlihat seperti ini:

{
  "model": "advertisement",
  "title": "Advertisement Generator",
  "capability": "IMAGE_GENERATION",
  "default_output_count": 1,
  "input_schema": { "type": "object", "properties": { "...": {} }, "required": ["prompt"] },
  "model_tiers": ["lite", "max"]
}

• model adalah slug yang Anda kirim sebagai field model. Hanya ini identifier yang penting.
• input_schema adalah JSON Schema yang menjelaskan objek input yang diterima model tersebut. Bacalah schema ini alih-alih menuliskan nama field secara hardcode — schema berbeda per model dan berubah seiring model berkembang.
• capability memberi tahu apa yang akan kembali: gambar, video, atau teks.
• model_tiers adalah tier kualitas yang bisa Anda kirim sebagai model_tier. Tier lebih tinggi memakan lebih banyak mood.

Bangun form atau validasi Anda dari input_schema. Kalau field-nya di-hardcode, pembaruan model akan merusak integrasi Anda tanpa suara: key yang tidak dikenal diteruskan begitu saja, dan key wajib yang hilang membuat permintaan gagal.

Template

Template adalah preset tersimpan untuk satu model — sebuah prompt beserta nilai input bawaan, biasanya dilengkapi pratinjau hasilnya.

curl 'https://api.mageran.ai/api/v1/templates?model=advertisement' \
  --header 'x-mager-api-key: YOUR_API_KEY'

{
  "template_id": "template_01hxyzready",
  "model": "advertisement",
  "media_url": "https://cdn.example.com/template-preview.png",
  "input": {
    "productName": "Mager Matcha Latte",
    "targetAudience": "Gen Z coffee shop customers",
    "brandTone": "fresh, playful, premium"
  },
  "preview_results": [{ "id": "preview_01hxyz", "media_url": "..." }]
}

GET /templates berhalaman dan menerima filter model serta templateCategoryId. GET /templates/{templateId} mengembalikan satu template.

Cara penggabungannya

Saat Anda mengirim template_id, Mager menggabungkan input milik template dengan input Anda. Nilai Anda yang menang.

{
  "model": "advertisement",
  "template_id": "template_01hxyzready",
  "input": { "productName": "Mager Cold Brew" }
}

Task berjalan dengan productName dari permintaan Anda serta targetAudience dan brandTone dari template. Tidak ada yang dibuang; Anda hanya menimpa apa yang Anda sebutkan.

Inilah alasan untuk memilih template pada apa pun yang dihadapkan ke pengguna: aplikasi Anda cukup mengirim dua atau tiga field, dan bagian yang butuh prompt engineering tetap tinggal di template.

Memilih di antara keduanya

Saat gagal

Slug model yang tidak dikenal atau template_id yang belum dipublikasikan mengembalikan 404. Input yang tidak memenuhi input_schema mengembalikan 422 beserta field yang gagal. Lihat Errors.