Image API responses: binary WebP or base64 JSON?

Choose binary for a direct image response

Set response_format to image to receive a WebP attachment. This is convenient for a server that forwards the result to a browser or writes it to a file. The successful response has Content-Type: image/webp and an attachment filename.

A cURL request can write that response directly with --output image.webp. Use --fail so an HTTP failure is not treated as a successful download. In application code, check response.ok first: errors are JSON, even when the requested success format is an image.

{
  "model": "magnt-image-1",
  "prompt": "A ceramic vase in soft daylight",
  "response_format": "image"
}

• Complete JavaScript download example

Choose JSON when you need dimensions in the response

The default response format is b64_json. Its data array contains b64_json, mime_type, width and height for the generated image. The response also identifies the Magnt model and creation time. Decode the base64 value into bytes before saving a normal image file.

Base64 is a transport encoding, not a different picture or a quality setting. It takes four encoded characters to represent a group of three input bytes, with padding where needed. JSON therefore carries more data than the binary image, which matters near request and response limits.

// After checking response.ok:
const result = await response.json();
const image = result.data[0];
if (image.mime_type !== "image/webp") throw new Error("Unexpected image type");
const bytes = Buffer.from(image.b64_json, "base64");
// Forward bytes or write them to a .webp file.

• Base64 format reference

Know what neither format provides

There is no hosted result URL, saved asset ID or recoverable generation job. If a customer needs to reopen an accepted image later, your application must keep that image. If the flow is a one-time download, you can simply deliver the response and let the user save it.

Responses use Cache-Control: no-store, private. Prompts and image bytes are not written to a Magnt image history. Authentication records and account usage are separate: key hashes, key metadata and allowance counters are persisted so access can be managed.

Handle size limits before they become UI surprises

Magnt normalises outputs to WebP and limits the generated file to 3 MiB. Request bodies are separately limited to 4 MiB, including inline images and JSON. A 413 response means a relevant size limit was exceeded; it is not a partially successful image.

For input-heavy edits, measure the encoded request before sending it. For display, preview the returned image and offer a deliberate download action. Do not assume that switching to JSON increases resolution or that a 2K request promises every output will have the same exact dimensions.

Use one response path first

Start with binary if your first feature is a download button. Start with JSON if your server already expects a structured payload and needs dimensions immediately. You can add support for the other format later without changing the Magnt key or model.

Either way, make the request once, handle its outcome and let the user choose the next action. Silent retries can create more generations than the user expected, especially after a timeout where completion is uncertain.

• Open the Magnt Image API