> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mage.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Inputs and uploads

> How to send images and video to the Mage API: which fields each model has, https URLs and data URLs, the upload endpoint for files over the request body limit, accepted formats, size limits, and retention.

Models that take an image or a video take it in named config fields. A model's page lists its media fields, and the [catalog](/api/endpoints/list-architectures) 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

Field names differ between models; read them from the model's page. The roles are the same everywhere.

| Role                  | Typical field             | Notes                                                              |
| --------------------- | ------------------------- | ------------------------------------------------------------------ |
| First frame           | `first_image`, or `image` | The image a video starts from. Required on image-to-video models.  |
| Last frame            | `last_image`              | The image a video ends on. Usually needs a first frame too.        |
| Reference image       | `image`                   | The first reference. On image models, the input image for an edit. |
| More reference images | `additional_images`       | A list. The model's rules cap how many.                            |
| Source video          | `video` or `videos`       | The video to edit or reference. `videos` is a list.                |

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    TICKET=$(curl --silent --request POST \
      --url https://api.mage.space/v1/uploads \
      --header "Authorization: Bearer $MAGE_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{ "content_type": "video/mp4" }')

    curl --request PUT \
      --url "$(echo "$TICKET" | jq -r .upload_url)" \
      --header "Content-Type: video/mp4" \
      --header "x-goog-content-length-range: 0,104857600" \
      --upload-file clip.mp4

    export INPUT_URL="$(echo "$TICKET" | jq -r .url)"
    ```

    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.
  </Step>
</Steps>

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

| Kind   | Formats        | Limit                                                         |
| ------ | -------------- | ------------------------------------------------------------- |
| Images | JPEG, PNG      | 100 MB per file                                               |
| Video  | MP4, MOV, WebM | 100 MB per file; each model caps the length of a source video |

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.

## 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`. 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.