Skip to main content
POST
Upload reference media and receive a public URL immediately on success; no polling is needed. Uploading is free, but your account balance must be positive. The three upload endpoints share a per-user quota, defaulting to 2000 files over 72 hours.
The documentation Playground does not support file uploads. Use the cURL, Python, or JavaScript examples below. The JavaScript example requires an <input type="file"> with a file selected on the page.

Authentication

string
required
Use a valid, enabled, unexpired APIMart API Key as Bearer <token>, with an account that is not suspended. The account balance must be positive; exhausting the Key’s own quota does not prevent uploads. Get a Key from API Key management.

Request parameters

file
required
Send one file, including its filename, in the file field of a multipart/form-data request. Do not substitute JSON, a base64 string, or a file URL for the file part. Other form fields are ignored; if multiple file parts are sent, only the first is processed.Supported formats: MP4 (.mp4), MOV (.mov), WebM (.webm)Default maximum file size: 50MB. File size limits can be configured. The active service configuration and size-limit error message take precedence.
With cURL --form, Python files, or JavaScript FormData, let the client generate the Content-Type header with its boundary. Do not set this header manually.

File validation

The file type is detected from its content, not its extension or the MIME type supplied by the client. The content must match the endpoint; renaming a file does not convert it. A type mismatch returns HTTP 400. Video container structure is validated. Fake file headers or damaged containers are rejected. Only the formats below are supported; renaming AVI, MKV, or other formats does not make them valid.

Successful response

HTTP 200 returns file metadata. url is at the JSON root, without a data wrapper or a generation task ID.
string
Public file URL. Pass it to the appropriate reference-media parameter of the target generation API. Each model still has its own format, size, count, and duration limits; a successful upload does not guarantee model compatibility.
string
Original filename.
string
MIME type detected by the server from the file content, not the client’s declared value.
string
File category. This endpoint returns video.
integer
Actual file size in bytes.
integer
Upload time as a Unix timestamp in seconds.
object
Optional upload quota information. Fields for a quota-limited user are listed below; unlimited access or temporarily unavailable statistics may produce a different structure, as explained below.

Shared quota and request rate limits

Image, video, and audio uploads share one per-user quota. Multiple API Keys for the same user do not add quota. The window rolls on the hour and, by default, counts successful uploads over approximately the past 71–72 hours. Invalid files, oversized files, and storage failures do not consume file quota. Normal quota-limited responses also include X-Upload-Quota-Limit, X-Upload-Quota-Remaining, and X-Upload-Quota-Reset, corresponding to limit, remaining, and reset_at. Reset is in Unix seconds. Unlimited users receive quota: {"unlimited": true} without those three quota headers. When statistics are temporarily unavailable, a successful response may omit quota. Do not interpret missing statistics as zero or unlimited, or re-upload solely because quota information is absent. Exhausted file quota returns HTTP 429 with error.type: rate_limit_exceeded, quota (remaining: 0), and Retry-After. Wait the specified number of seconds before retrying. A separate limit of 1000 requests per Key per 60 seconds uses rate_limit_error; it is independent of the file quota.

Error handling

Errors use a root-level error object. Inspect the HTTP status, error.type / error.code, and error.message to determine the cause.

Using URLs and retaining files

72 hours is the default quota window, not a file-retention guarantee. Retention depends on the storage policy. Keep the original files and use returned URLs promptly for generation; do not assume URLs are permanent.

Other upload endpoints