Models and templates

Two endpoints decide what you can send to POST /generation-tasks.

Models

GET /models returns everything Mager can generate. Each entry looks like this:

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

• model is the slug you send as the model field. It is the only identifier that matters.
• input_schema is a JSON Schema describing the input object that model accepts. Read it instead of hardcoding field names — schemas differ per model and change as models improve.
• capability tells you what comes back: an image, a video, or text.
• model_tiers are the quality tiers you can pass as model_tier. Higher tiers cost more moods.

Build your form or your validation from input_schema. If you hardcode fields, a model update breaks you silently: unknown keys are passed through, and missing required keys fail the request.

Templates

A template is a saved preset for one model — a prompt plus default input values, usually with a preview of what it produces.

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 is paginated and accepts model and templateCategoryId filters. GET /templates/{templateId} returns one.

How the merge works

When you pass a template_id, Mager merges the template's input with yours. Your values win.

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

The task runs with productName from your request and targetAudience and brandTone from the template. Nothing is dropped; you only override what you name.

This is the reason to prefer templates for anything user-facing: your application sends two or three fields, and the parts that take prompt engineering stay in the template.

Choosing between them

When it fails

An unknown model slug or a template_id that is not published returns 404. Input that does not satisfy input_schema returns 422 with the failing fields. See Errors.