Skip to main content
Models that take an image or a video take it in named fields. A model’s page lists its media fields, and the catalog reports them as image_inputs and video_inputs, so a client can tell an image-to-video model from a text-only one before it submits.

​
Where inputs go

The roles and the field names are the same on every model.

​
Three ways to send a file

Every media field accepts either an https URL or a data URL. Before the run, Mage brings each input onto its own storage, so the model only ever reads from Mage.
1

An https URL

Any public https URL that serves the file with the right content type. Mage downloads it, following up to 3 redirects, within 60 seconds and 100 MB. Private and internal hosts are refused. A URL that serves another content type, or that cannot be fetched, is a 400 invalid_config naming the field.
2

A data URL

data:image/png;base64,... with the file inline. Request bodies are capped at 4.5 MB, so a data URL carries about 3 MB of file. Use it for small images; use an upload for anything larger.
3

An upload

For files too large for a data URL, and for files that are not on a public URL, create an upload ticket and PUT the file to Mage storage. Then send the returned url in any media field, or as the voice or audio of a character or audio reference you create.
Send every header in the ticket’s headers exactly as returned; storage checks them against the signature. The upload URL is valid for 15 minutes (upload_url_expires_at). Do not send your API key to the upload URL.
The SDKs do both steps in one call: uploads.upload in the TypeScript and Python SDKs creates the ticket, sends the file with the right headers, and returns the url to use. A URL that already points at Mage storage, such as the result of an earlier request or an upload, is used as it is. Mage checks that it still exists; an expired one is refused before anything is charged, with a message asking you to upload it again.

​
Formats and limits

Audio is taken only when you create a character or an audio reference; a generate request mentions the saved clip by @handle. Formats are checked by the content type the file is served or declared with, not by its extension.

​
Video is measured for you

Mage measures every source video after it is stored and fills in its duration, and its dimensions where a model needs them. Do not send video_duration_s, video_durations_s, video_width, or video_height; the measured values are what the model rules and billing use.

​
Retention

Inputs are stored in the same 30-day temporary area as results, so an input expires with the generations it fed. An upload ticket reports the file’s deletion time as url_expires_at. Keep your own copy of anything you may need to send again. The one exception is the media of a saved character or reference, which is kept for as long as the entity exists.

​
Characters and references

A saved character is one image, a handle, and optionally a voice; a reference is one image of an object, location, pose, or outfit, or one audio clip. Both are the same entities as in the app: create them in the app or with POST /v1/characters and POST /v1/references, list yours with the GET endpoints, and use them by writing @handle in prompt, exactly as a user types it in the app.
  • What resolves. Every @handle is matched, case-insensitively, against your own characters, image references, and audio references, and against public characters. Mage attaches the entity’s image or clip to the request and rewrites the mention to the positional phrase the model reads, so the prompt may say where and how the entity appears, in natural language.
  • What is refused. A handle that matches nothing, a handle on a model that does not support that kind of entity, and more mentions than the model’s budget allows are each a 400 invalid_config naming the handle, before anything is charged. Any @ followed by letters is read as a handle, so an email address in a prompt is refused too. The models that accept each kind, and their budgets, are in the mentions and max_images fields of the catalog and on each model’s page.
  • Budgets. Image inputs, characters, and references share one budget per request (max_images). Audio references and character voices share another (mentions.max_audio_references).
  • Voices follow characters. On the models that support character voices (mentions.character_voices), a mentioned character’s voice clip is sent with its image and counts as an audio source. Send use_character_voices: false to leave the voices out.
  • Your own image inputs by position. On models that support characters or references, @image1, @image2, and so on refer to the request’s own image inputs in order (image, then additional_images); other models refuse them, and a number past the inputs you sent is refused like an unknown handle. The image<N> handles are reserved, so no entity can take one: "@image1 wearing @red-coat".
  • Handles can change hands. A deleted entity’s handle may be taken again, by you or, for public characters, by anyone. Store the id from the list endpoints if you need to detect that a handle now names something else.

​
Fields you cannot set

A few config fields belong to the server and are refused with 400 invalid_request when a request includes them: app, characters, references, moodboard, moodboard_sampled_images, audio_references, prompt_filter, dynamic_prompt, fast_mode, use_gems, and wait_time_s. Characters, references, and audio references are attached by @handle in the prompt, never as objects; Moodboards and in-app prompt styling are not available through the API, so send the finished prompt and the inputs themselves. A body may carry architecture as long as it matches the endpoint; a contradicting value is refused. Fields the model’s schema does not list pass through to the model unchanged and are never refused.
Last modified on September 30, 2026