# Start an image or video upload

> Start an image or video upload with the Wavegrain Posting API: POST /api/v1/media. Request body, responses and an example request.

> Index of these docs: https://wavegrain.com/developers/llms.txt

`POST /api/v1/media` is part of the [Posting API](/developers/posting-api). Every call needs an access key: see [Authentication](/developers/authentication).

Needs the `write` permission.

An image answers one upload address. PUT the file's bytes there once, within 10 minutes, with the same `Content-Type` and no `Authorization` header. JPEG, PNG or WebP, at most 15 MB; the file is checked by its bytes and stored in your Wavegrain images, at most 2400 px on the long side.

A video (MP4 or MOV, at most 4 GB) answers a multipart upload: PUT each part's bytes to its own address (no `Authorization` header), then call POST /api/v1/media/{id}/complete. Every part but the last has exactly `partSize` bytes. A part that fails is sent again on its own; GET /api/v1/media/{id} lists the parts still missing with fresh addresses. An upload not completed within a day is dropped.

Images count toward the daily upload budget, videos toward a daily video budget of their own, and both toward the plan's storage. A video is kept 7 days, and longer while a post that waits or has not been sent uses it.

## Request body

The body takes one of 2 shapes.

**When `kind` is `"image"`**

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `kind` | "image" | yes |  |
| `mime` | "image/jpeg" \| "image/png" \| "image/webp" | yes |  |
| `bytes` | integer | yes | The file's size in bytes. |
| `filename` | string | no |  |

**When `kind` is `"video"`**

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `kind` | "video" | yes |  |
| `mime` | "video/mp4" \| "video/quicktime" | yes | MP4 or MOV, with H.264 or HEVC video and AAC audio. |
| `bytes` | integer | yes | The file's exact size in bytes, at most 4 GB (4,000,000,000). |
| `filename` | string | no |  |

## Example request

```bash
curl -X POST https://wavegrain.com/api/v1/media \
  -H "Authorization: Bearer $WAVEGRAIN_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"image","mime":"image/jpeg","bytes":482113,"filename":"slide-1.jpg"}'
```

## Responses

| Status | Meaning |
| --- | --- |
| 201 | The upload address (an image), or the upload and its parts (a video), and the id to use in a post. |
| 400 | Not a file type Wavegrain takes, or too large. |
| 401 | No access key, or an unknown, revoked or expired one |
| 402 | The plan's storage is full. |
| 403 | The key lacks the permission, or the account has no active plan |
| 409 | Video posts are turned off on Wavegrain for now. |
| 429 | The day's upload budget is spent, or too many requests. |
| 500 | Something went wrong on Wavegrain's side; try again, and send the request id if it keeps failing. |
| 503 | Video storage is not set up on this server (`not_configured`), so a video upload cannot start. |

A successful answer:

```json
{
  "id": "upl_a8Zk2Qw",
  "uploadUrl": "https://wavegrain.com/api/tailored/uploads/upl_a8Zk2Qw?token=eyJ1cGxvYWQiOiJ1cGxfYThaazJRdyJ9",
  "method": "PUT",
  "contentType": "image/jpeg",
  "maxBytes": 15728640,
  "expiresAt": "2026-11-07T08:20:00.000Z"
}
```

## More in the Posting API

- [List brands, groups and connected accounts](/developers/api/list-accounts): `GET /api/v1/accounts`
- [List posts](/developers/api/list-posts): `GET /api/v1/posts`
- [Create a post](/developers/api/create-post): `POST /api/v1/posts`
- [Get a post](/developers/api/get-post): `GET /api/v1/posts/{id}`
- [Cancel a post](/developers/api/cancel-post): `DELETE /api/v1/posts/{id}`
- [Get an upload](/developers/api/get-upload): `GET /api/v1/media/{id}`
- [Delete a video](/developers/api/delete-video): `DELETE /api/v1/media/{id}`
- [Finish and check a video upload](/developers/api/complete-video-upload): `POST /api/v1/media/{id}/complete`
- [Write captions](/developers/api/write-captions): `POST /api/v1/captions`
- [All endpoints](/developers/api)
