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"

FieldTypeRequiredNotes
kind"image"yes
mime"image/jpeg" | "image/png" | "image/webp"yes
bytesintegeryesThe file's size in bytes.
filenamestringno

When kind is "video"

FieldTypeRequiredNotes
kind"video"yes
mime"video/mp4" | "video/quicktime"yesMP4 or MOV, with H.264 or HEVC video and AAC audio.
bytesintegeryesThe file's exact size in bytes, at most 4 GB (4,000,000,000).
filenamestringno

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

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

Something wrong or missing? Write to support@wavegrain.com.