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
Field names differ between models; read them from the model’s page. The roles are the same everywhere.Three ways to send a file
Every media field accepts either anhttps 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 Send every header in the ticket’s
PUT the file to Mage storage. Then send the returned url in any media field.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.Formats and limits
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 sendvideo_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 asurl_expires_at. Keep your own copy of anything you may need to send again.
Fields you cannot set
A few config fields belong to the server and are refused with400 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. Saved Characters, References, Moodboards, audio references, and in-app prompt styling are not available through the API yet; 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.