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.
POST /api/v1/media is part of the Posting API. Every call needs an access key: see 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
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:
{
"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:
GET /api/v1/accounts - List posts:
GET /api/v1/posts - Create a post:
POST /api/v1/posts - Get a post:
GET /api/v1/posts/{id} - Cancel a post:
DELETE /api/v1/posts/{id} - Get an upload:
GET /api/v1/media/{id} - Delete a video:
DELETE /api/v1/media/{id} - Finish and check a video upload:
POST /api/v1/media/{id}/complete - Write captions:
POST /api/v1/captions - All endpoints
Something wrong or missing? Write to support@wavegrain.com.