Skip to main content

​
Step 1: Request a presigned upload URL

curl -X POST https://api.modelroute.ai/v1/files/upload \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "input-photo.png",
    "content_type": "image/png",
    "size_bytes": 2048576
  }'

​
Request body

FieldTypeRequiredDescription
filenamestringYesOriginal filename (used for content-type validation)
content_typestringYesMIME type (e.g., image/png, audio/mp3, video/mp4)
size_bytesintegerYesFile size in bytes. Maximum: 104,857,600 (100 MB)

​
Response

{
  "file_id": "file_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "upload_url": "https://storage.modelroute.ai/uploads/file_f47ac10b...?X-Amz-Signature=...",
  "expires_at": "2026-03-20T11:30:00Z"
}
FieldDescription
file_idThe file reference to use in execution inputs
upload_urlPresigned PUT URL. Valid for 1 hour.
expires_atWhen the upload URL expires

​
Step 2: Upload the file

Use an HTTP PUT request to upload the file to the presigned URL: 
curl -X PUT "https://storage.modelroute.ai/uploads/file_f47ac10b...?X-Amz-Signature=..." \
  -H "Content-Type: image/png" \
  --data-binary @input-photo.png
The Content-Type header in the PUT request must match the content_type you specified in step 1. Mismatched types will be rejected.

​
Step 3: Use the file reference

Pass the file_id in your execution input: 
curl -X POST https://api.modelroute.ai/v1/executions \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1.1-pro",
    "input": {
      "prompt": "Transform this photo into an oil painting",
      "image": "file_f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  }'

​
Error handling

Error codeCause
INPUT_VALIDATION_ERRORMissing filename, invalid content_type, or size exceeds 100 MB
FILE_FORMAT_UNSUPPORTEDThe model does not support this file format
FILE_NOT_FOUNDThe file reference does not exist or the upload was not completed
INSUFFICIENT_BALANCENot enough balance to process the execution with this file

​
Complete upload flow example

import requests

API_KEY = "sk_your_api_key_here"
BASE = "https://api.modelroute.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Request presigned URL
upload_resp = requests.post(
    f"{BASE}/files/upload",
    headers=HEADERS,
    json={
        "filename": "photo.png",
        "content_type": "image/png",
        "size_bytes": 2048576
    }
).json()

file_id = upload_resp["file_id"]
upload_url = upload_resp["upload_url"]

# 2. Upload the file
with open("photo.png", "rb") as f:
    requests.put(upload_url, data=f, headers={"Content-Type": "image/png"})

# 3. Use in execution
result = requests.post(
    f"{BASE}/executions",
    headers=HEADERS,
    json={
        "model": "flux-1.1-pro",
        "input": {
            "prompt": "Make this photo look like a watercolor painting",
            "image": file_id
        }
    }
).json()

print(f"Execution {result['id']}: {result['status']}")