API reference

One endpoint makes new images and edits photos you attach. Send JSON, get one WebP back, as raw bytes or base64. Images only: video is made in the Magnt app.

Base URLhttps://magnt.app/api/v1

Authentication

Create a key at magnt.app/developers while signed in. Keys look like mgnt_ followed by 64 hex characters. Store it in a server variable named MAGNT_API_KEY and send it on every request. Never ship it in a browser bundle or app source.

Authorization: Bearer $MAGNT_API_KEY

Each account can hold 10 active keys. Revoked keys fail on the next request. Every key spends the same account's plan credits.

POST/api/v1/images/generations

Create an image

Leave images empty to generate from the prompt. Attach photos to edit them, and say what should change and what should stay. Each request stands alone, so send the photos again for the next edit. Set Content-Type to application/json.

Request body

FieldTypeDefaultDescription

prompt: string; required; What to make or change. 1 to 4,000 characters after trimming.
model: string; magnt-image-1; A model ID from GET /api/v1/models.
images: string[]; []; Up to 3 base64 data URLs: data:image/png, image/jpeg or image/webp. Remote URLs are not accepted.
aspect_ratio: enum; 1:1; 1:1, 4:5, 3:2, 2:3, 16:9 or 9:16.
resolution: enum; 1K; 1K or 2K.
response_format: enum; b64_json; image returns raw WebP bytes. b64_json returns JSON with the image encoded.

Only these fields are accepted. Anything else returns invalid_request.

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",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "response_format": "image"
  }' --output image.webp

Response

Success is HTTP 200 with exactly one image. Nothing is hosted, so there's no URL to fetch later. Save what you need.

"image"

Raw bytes. Content-Type is image/webp, downloaded as magnt-image.webp. Check the status before writing the file.

// "b64_json" (default)
{
  "created": 1788912000,
  "model": "magnt-image-1",
  "data": [{
    "b64_json": "UklGRm...",
    "mime_type": "image/webp",
    "width": 1024,
    "height": 1024
  }]
}

Errors

Errors are always JSON, even when you asked for image bytes. Validation errors add error.details. A failed or interrupted request gives its credit back.

{
  "error": {
    "code": "rate_limited",
    "message": "Your Magnt generation limit was reached. Try again later."
  }
}

StatusCodeWhat to do

400: invalid_json, invalid_request, invalid_image, provider_rejected_request; Fix the JSON, fields, image or prompt, then retry.
401: api_key_required, invalid_api_key; Send an active key with the Bearer scheme.
402: allowance_required; Add a plan or a top-up to the account that owns the key.
413: payload_too_large, output_too_large; Send smaller images, or ask for 1K.
415: unsupported_media_type; Set Content-Type to application/json.
422: image_not_generated; No image came back. Rework the prompt or inputs.
429: rate_limited, provider_rate_limited; Wait, then retry. Avoid tight retry loops.
502: generation_failed, provider_unavailable, invalid_provider_output, output_unavailable; Something broke on our side. Try again later.
503: model_unavailable, provider_auth_failed, provider_balance_required; Temporarily unavailable. Check GET /models or contact support.
504: generation_interrupted; It may still finish. Don't resubmit straight away.

Limits and rate limits

Rate limit: 30 requests an hour per account, shared by all its keys. A new key doesn't reset it.
Request body: 4 MiB, base64 included.
Input images: Up to 3. Each 2 MiB decoded, under 25 megapixels, PNG, JPEG or WebP, not animated.
Output: One WebP, up to 3 MiB.
Time: Requests stop after 180 seconds with generation_interrupted.
Keys: 10 active per account.

GET/api/v1/models

List models

Public, no key needed. Returns the models you can call right now. An empty list means none are available, so hide your Generate button.

{
  "data": [{
    "id": "magnt-image-1",
    "name": "Magnt Image",
    "aspect_ratios": ["1:1", "4:5", "3:2", "2:3", "16:9", "9:16"],
    "resolutions": ["1K", "2K"],
    "max_input_images": 3,
    "output_format": "webp"
  }]
}