Skip to main content

​
Small files

POST /media (write) takes a small image, GIF or video as the whole body, with its Content-Type. It returns a media_id to pass in media_ids when creating a post.

​
Chunked uploads

Use chunks for files larger than the server’s 16 MiB request limit, or to retry an interrupted upload. Each segment can be up to 5 MiB. The instance’s image and video limits still apply.
1

Start

POST /media/uploads with the file’s MIME type and exact byte length. Save the returned media_id.
2

Send segments

Send consecutive segments to POST /media/{id}/segments/0, /1, and so on, as raw binary bodies. You can send them out of order and retry an index without counting its bytes twice.
3

Resume if needed

Read GET /media/{id}. While processing is uploading, segments lists each received segment_index and its bytes.
4

Finalize

POST /media/{id}/finalize. You can retry it. If processing is still pending, poll GET /media/{id} after check_after_secs.
5

Publish

Use the media_id in a post once processing is succeeded. A failed result includes an error: fix the file and start a new upload.

​
Rules

  • Pending uploads expire after an hour.
  • Upload state lives in the server process. If the server restarts, start a new upload.
  • You can have up to eight pending uploads.
  • Only tokens for the account that started an upload can inspect or change it.
  • Starting an upload counts toward the upload limit. Sending segments and finalizing use the normal write limit; progress checks use the read limit.