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

# How to Use

> Upload media files with the Modellix File API, pass the returned URL into prediction APIs, and manage retention and upload quota.

Use the File API to upload images, videos, and audio that you can pass into Modellix prediction APIs. Uploads are authenticated with your API Key and are not billed. Files are retained for a limited time (default **7 days**).

<CardGroup cols={3}>
  <Card title="Upload Media File" icon="upload" href="/api/upload-media-file">
    Upload a single file via `multipart/form-data`.
  </Card>

  <Card title="List Media Files" icon="list" href="/api/list-media-files">
    List non-expired files for your team.
  </Card>

  <Card title="Delete Media File" icon="trash" href="/api/delete-media-file">
    Delete a file and free upload quota immediately.
  </Card>
</CardGroup>

## Prerequisites

* A Modellix [API Key](https://modellix.ai/console/api-key)
* A local media file within the [size and format limits](#limits-and-supported-formats)

## Typical workflow

<Steps>
  <Step title="Upload a file">
    Send a `POST` request to `/api/v1/media/files` with `multipart/form-data`. The form field name must be `file`.

    The file must use a supported extension and contain valid content for that type.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST 'https://api.modellix.ai/api/v1/media/files' \
        -H 'Authorization: Bearer $API_KEY' \
        -F 'file=@./image.png'
      ```

      ```python Python theme={null}
      import os
      import requests

      resp = requests.post(
          "https://api.modellix.ai/api/v1/media/files",
          headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
          files={"file": open("image.png", "rb")},
      )
      print(resp.json())
      ```
    </CodeGroup>

    On success, the response includes a `file_id`, media `type` (`image`, `video`, or `audio`), and a `url`:

    ```json theme={null}
    {
      "code": 0,
      "message": "success",
      "data": {
        "file_id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "image",
        "url": "https://file.modellix.ai/example/550e8400-e29b-41d4-a716-446655440000.png",
        "filename": "image.png",
        "size": 102400,
        "created_at": 1784084400000
      }
    }
    ```
  </Step>

  <Step title="Use the file URL in a model API">
    Pass `data.url` into the image, video, or audio input fields of a prediction API (for example `image_url`).

    ```bash theme={null}
    curl --request POST \
      --url https://api.modellix.ai/api/v1/alibaba/qwen-image-edit/async \
      --header 'Authorization: Bearer $API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "prompt": "Change the background to a sunny garden",
        "image_url": "https://file.modellix.ai/example/550e8400-e29b-41d4-a716-446655440000.png"
      }'
    ```

    <Tip>
      Prefer the returned `url` over hosting the asset yourself when you only need a temporary public URL for model input.
    </Tip>
  </Step>

  <Step title="List files (optional)">
    List media files that belong to your team and have not yet expired. Default page size is `100`; `limit` is capped at `100`.

    ```bash theme={null}
    curl -X GET 'https://api.modellix.ai/api/v1/media/files?limit=10&offset=0' \
      -H 'Authorization: Bearer $API_KEY'
    ```

    ```json theme={null}
    {
      "code": 0,
      "message": "success",
      "data": {
        "items": [
          {
            "file_id": "550e8400-e29b-41d4-a716-446655440000",
            "type": "image",
            "url": "https://file.modellix.ai/example/550e8400-e29b-41d4-a716-446655440000.png",
            "filename": "image.png",
            "size": 102400,
            "created_at": 1784084400000
          }
        ],
        "total": 1,
        "limit": 100,
        "offset": 0
      }
    }
    ```
  </Step>

  <Step title="Delete files you no longer need">
    Delete a file you no longer need. After deletion, it no longer counts toward your upload limit.

    ```bash theme={null}
    curl -X DELETE 'https://api.modellix.ai/api/v1/media/files/550e8400-e29b-41d4-a716-446655440000' \
      -H 'Authorization: Bearer $API_KEY'
    ```

    ```json theme={null}
    {
      "code": 0,
      "message": "success",
      "data": {}
    }
    ```

    <Note>
      Returns `404` if the file is not found.
    </Note>
  </Step>
</Steps>

## Limits and supported formats

### Default limits

| Limit                       | Default      |
| --------------------------- | ------------ |
| Max file size               | 16 MB        |
| Files per team              | 10           |
| Concurrent uploads per team | 2            |
| Retention                   | About 7 days |

<Warning>
  Files expire after the retention window. Delete unused files early if you are approaching the per-team file count limit.
</Warning>

### Allowed file extensions

| Category | Extensions                                                                |
| -------- | ------------------------------------------------------------------------- |
| image    | `jpg`, `jpeg`, `png`, `webp`, `gif`, `bmp`, `tiff`, `tif`, `heic`, `heif` |
| video    | `mp4`, `m4v`, `webm`, `mov`, `mkv`, `avi`                                 |
| audio    | `mp3`, `wav`, `m4a`, `aac`, `ogg`, `flac`, `opus`, `weba`                 |

The response `type` field is derived from the extension and is one of `image`, `video`, or `audio`.

## Error handling

Error responses use the same JSON shape as other Modellix APIs:

```json theme={null}
{
  "code": 400,
  "message": "Invalid format: unsupported file format"
}
```

| HTTP status | Common causes                                                                            |
| ----------- | ---------------------------------------------------------------------------------------- |
| 400         | Missing `file`, unsupported format, content mismatch, invalid image, or rejected content |
| 401         | Missing or invalid API Key                                                               |
| 404         | File not found (delete only)                                                             |
| 413         | File exceeds the maximum allowed size                                                    |
| 429         | Upload quota or concurrency limit exceeded                                               |
| 500         | Internal server error                                                                    |

## Next steps

* [Upload Media File](/api/upload-media-file) — full request and response schema
* [List Media Files](/api/list-media-files) — pagination parameters
* [Delete Media File](/api/delete-media-file) — path parameter and delete behavior
* [REST API](/ways-to-use/api) — authenticate, submit async tasks, and poll results