Uploads
Host files on AITOPIA to use them as model or edit input.
Use uploads when your file is not already at a public URL. Uploads are not charged. Limits and the upload-link PUT step are described in File uploads.
| Method | Path | Summary |
|---|---|---|
POST | /v1/uploads | Host a file (base64 up to about 19 MB, or import from source_url). |
POST | /v1/uploads/link | Get a one-time upload URL for files up to 95 MB (PUT the bytes; the answer holds the file URL). |
#POST /v1/uploads
Host a file (base64 up to about 19 MB, or import from source_url).
Authentication: Authorization: Key <key>.
Send exactly one of content_base64 (with content_type; about 19 MB of file fits in the 25 MB body) or source_url (downloaded by AITOPIA, up to 200 MB). With source_url, pass a file_name with an extension or a content_type.
#Request body
Content type application/json.
| Field | Type | Required | Description |
|---|---|---|---|
content_base64 | string | no | |
content_type | string | no | |
file_name | string | no | |
source_url | string (uri) | no | Use instead of content_base64. |
#Responses
| Status | Description | Body |
|---|---|---|
200 | Hosted file | object |
400 | INVALID_INPUT (with field), URL_NOT_ALLOWED, MODEL_REQUIRED, MODEL_KIND_MISMATCH, MODEL_NOT_ALLOWED, DUPLICATE_ITEM or INVALID_RUN_TOKEN | Error |
401 | UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key) | Error |
413 | FILE_TOO_LARGE or INPUT_TOO_LARGE | Error |
429 | RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header) | Error |
500 | INTERNAL_ERROR (an unexpected server error) | Error |
#Example
curl -X POST "https://api-live.aitopia.ai/v1/uploads" \
-H "Authorization: Key $AITOPIA_KEY" \
-H "Content-Type: application/json" \
-d '{"source_url":"https://example.com/photo.png","file_name":"photo.png"}'{
"url": "https://cdn.aitopia.ai/...",
"content_type": "image/png",
"size": 482113
}#POST /v1/uploads/link
Get a one-time upload URL for files up to 95 MB (PUT the bytes; the answer holds the file URL).
Authentication: Authorization: Key <key>.
Then PUT the raw file to upload_url (no Authorization header; valid once, for 10 minutes). The PUT answers with the file's assetUrl. See File uploads.
#Request body
Content type application/json (optional).
| Field | Type | Required | Description |
|---|---|---|---|
file_name | string | no | |
content_type | string | no |
#Responses
| Status | Description | Body |
|---|---|---|
200 | Upload link | object |
401 | UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key) | Error |
429 | RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header) | Error |
500 | INTERNAL_ERROR (an unexpected server error) | Error |
#Example
curl -X POST "https://api-live.aitopia.ai/v1/uploads/link" \
-H "Authorization: Key $AITOPIA_KEY" \
-H "Content-Type: application/json" \
-d '{"file_name":"clip.mp4","content_type":"video/mp4"}'{
"upload_url": "https://.../uploads/...",
"file_url": null,
"expires_at": "2026-10-23T10:10:00.000Z",
"max_bytes": 99614720
}