Image API reference

Authentication

Create a Magnt API key while signed in, then store it in a server environment variable named MAGNT_API_KEY. Send Authorization: Bearer YOUR_MAGNT_API_KEY with generation requests. Keep the secret on your server, outside browser bundles and mobile app source.

Keys belong to your account and can be revoked from the playground. API generations use the same account allowance as the app: one plan generation or two legacy credits per successful image. Creating a key does not provide extra generations. View plans and allowances.

Generate your first image with cURL

Set your environment variable, then run this request from your terminal. On success, it writes WebP bytes to image.webp. A nonzero cURL exit status means the file may contain an error response instead of an image.

curl --fail-with-body https://magnt.app/api/v1/images/generations \
  -H "Authorization: Bearer $MAGNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "magnt-image-1",
    "prompt": "A ceramic cup on a linen table, natural window light, realistic product photography",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "response_format": "image"
  }' --output image.webp

Prefer a language guide? Follow the JavaScript image generation tutorial or Python image generation tutorial.

POST /api/v1/images/generations

Send a JSON body with Content-Type: application/json. Only the fields below are accepted; unknown fields return an invalid request error. The same endpoint handles text-to-image generation and photo editing.

For editing, encode the source photo as a base64 data URL in images and describe what should change and what should stay the same. Each request is independent; include the relevant images again for subsequent edits. See the inline image editing guide.

WebP image and base64 JSON responses

A successful request returns HTTP 200. With response_format: "image", read the response as binary image data with Content-Type: image/webp. With response_format: "b64_json", parse JSON and decode data[0].b64_json to save the image.

{
  "created": 1788912000,
  "model": "magnt-image-1",
  "data": [
    {
      "b64_json": "BASE64_ENCODED_WEBP_BYTES",
      "mime_type": "image/webp",
      "width": 1024,
      "height": 1024
    }
  ]
}

This is an illustrative response. The timestamp, image bytes and dimensions vary. There is no hosted output URL or saved photo history in the API; your app handles storage and delivery.

Image sizes and request limits

The complete JSON body must fit within 4 MiB, including base64 encoding overhead. Each decoded input image must be at most 2 MiB. Use non-animated PNG, JPEG or WebP images under 25 megapixels, with no more than three images per request. The generated WebP response is limited to 3 MiB.

Generation is limited to 30 requests per hour per account, shared across that account’s keys. A new key does not reset the limit. Review generated details before publishing, especially faces, text, labels and product features.

Error codes and retry handling

Errors return JSON with an error.code and error.message, even when you request image bytes. Field validation errors also include error.details. Check the HTTP status before interpreting the body as an image.

GET /api/v1/models

This public endpoint returns the currently available models in a data array. Each model includes id, name, aspect_ratios, resolutions, max_input_images and output_format. An empty array means no model is currently available. Use it to populate your integration’s model picker.

Try the image API playground or explore image generation and editing use cases.