How to Use - Modellix

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

Upload Media File

Upload a single file via multipart/form-data.

List Media Files

List non-expired files for your team.

Delete Media File

Delete a file and free upload quota immediately.

Prerequisites

A Modellix API Key
A local media file within the size and format limits

Typical workflow

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.

curl -X POST 'https://api.modellix.ai/api/v1/media/files' \
  -H 'Authorization: Bearer $API_KEY' \
  -F 'file=@./image.png'

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())

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

{
  "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
  }
}

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

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"
  }'

Prefer the returned url over hosting the asset yourself when you only need a temporary public URL for model input.

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.

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

{
  "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
  }
}

Delete files you no longer need

Delete a file you no longer need. After deletion, it no longer counts toward your upload limit.

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

{
  "code": 0,
  "message": "success",
  "data": {}
}

Returns 404 if the file is not found.

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

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

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:

{
  "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 — full request and response schema
List Media Files — pagination parameters
Delete Media File — path parameter and delete behavior
REST API — authenticate, submit async tasks, and poll results

Upload Media File

List Media Files

Delete Media File

​Prerequisites

​Typical workflow

​Limits and supported formats

​Default limits

​Allowed file extensions

​Error handling

​Next steps

Prerequisites

Typical workflow

Limits and supported formats

Default limits

Allowed file extensions

Error handling

Next steps