Upload a file

POST /api/uploads

Multipart upload using the file field. Caps: images 25 MiB, GIFs 50 MiB, audio 100 MiB, video 300 MiB. Account storage defaults to 2 GiB but can vary; read usage.maxTotalBytes from the list response. Use upload.url as an element source.

Authentication

• Option 1: x-api-key: YOUR_API_KEY (header). API key for authentication. Create one in your dashboard.
• Option 2: Authorization: Bearer YOUR_ACCESS_TOKEN. Dashboard JWT in Authorization: Bearer <token>, only on operations that explicitly list this scheme. Prefer x-api-key for REST integrations. OAuth for hosted MCP is a separate connection at https://mcp.zvid.io/mcp.

Create API keys at app.zvid.io/api-keys. Keep credentials on your server.

Parameters

This operation has no path, query, or additional header parameters.

Request

The shell examples read credentials from ZVID_API_KEY (or ZVID_ACCESS_TOKEN for Bearer authentication). Set that variable in your environment. Replace sample project, template, job, and asset identifiers with values from your own account.

A request body is required.

multipart/form-data

Required properties: file.

Field	Type	Required	Description and constraints
body.file	string	Yes	Format: binary.

Request example

curl --request POST 'https://api.zvid.io/api/uploads' \
  --header "x-api-key: $ZVID_API_KEY" \
  --form "file=@/path/to/your-file.png"

Responses

HTTP 201

New upload metadata

Content type: application/json.

Required properties: upload.

Field	Type	Required	Description and constraints
response.upload	Upload	Yes

Representative successful response response

{
  "upload": {
    "id": "upl_example",
    "kind": "image",
    "fileName": "photo.jpg",
    "mimeType": "image/jpeg",
    "sizeBytes": 12345,
    "width": 1200,
    "height": 630,
    "duration": null,
    "url": "https://example.com/photo.jpg",
    "createdAt": "2026-09-22T12:00:00Z"
  }
}

HTTP 400

Unsupported type or size/quota exceeded

Content type: application/json.

Required properties: error.

Field	Type	Required	Description and constraints
response.error	string	Yes
response.message	string	No
response.details	array of object	No
response.planLimits	object	No	Present on render validation errors; contains the authenticated user's current render limits.

Nested field: response.details

Array item: response.details[]

Unknown properties are rejected. Required properties: field, message.

Field	Type	Required	Description and constraints
response.details[].field	string	Yes
response.details[].message	string	Yes

Schema definitions

The following definitions describe the fields referenced above. Expand a definition to inspect its complete contract.

Upload

Required properties: id, kind, fileName, sizeBytes, url.

Field	Type	Required	Description and constraints
Upload.id	string	Yes
Upload.kind	"image" / "video" / "audio" / "gif"	Yes
Upload.fileName	string	Yes
Upload.mimeType	string	No
Upload.sizeBytes	integer	Yes
Upload.width	number OR null	No	At least one listed alternative must match.
Upload.height	number OR null	No	At least one listed alternative must match.
Upload.duration	number OR null	No	At least one listed alternative must match.
Upload.url	string	Yes
Upload.createdAt	string	No

Nested field: Upload.width

At least one listed alternative must match.

anyOf alternative 1

Type: number.

anyOf alternative 2

Type: null.

Nested field: Upload.height

At least one listed alternative must match.

anyOf alternative 1

Type: number.

anyOf alternative 2

Type: null.

Nested field: Upload.duration

At least one listed alternative must match.

anyOf alternative 1

Type: number.

anyOf alternative 2

Type: null.

ValidationError

Required properties: error.

Field	Type	Required	Description and constraints
ValidationError.error	string	Yes
ValidationError.message	string	No
ValidationError.details	array of object	No
ValidationError.planLimits	object	No	Present on render validation errors; contains the authenticated user's current render limits.

Nested field: ValidationError.details

Array item: ValidationError.details[]

Unknown properties are rejected. Required properties: field, message.

Field	Type	Required	Description and constraints
ValidationError.details[].field	string	Yes
ValidationError.details[].message	string	Yes

Related resources

• OpenAPI specification
• Project payload schema
• Quick Start
• Authentication guide