---
title: "Upload a file"
canonical_url: https://docs.zvid.io/docs/endpoints/create-upload/
source: docs/endpoints/create-upload.api.mdx
content_revision: 6338386a1dd87e4a
---

# 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](https://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

```bash
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](#schema-upload) | Yes |  |


**Representative successful response response**

```json
{
  "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.


### schema upload

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


### schema validation error

**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](https://docs.zvid.io/openapi.yaml)
- [Project payload schema](https://docs.zvid.io/schemas/render-payload.schema.json)
- [Quick Start](https://docs.zvid.io/docs/quick-start/)
- [Authentication guide](https://docs.zvid.io/docs/authentication/)