Skip to main content

Upload media

POST 
/media/upload

Request a presigned upload URL for a media file. This is step 1 of the 3-step upload flow:

  1. POST /media/upload — Get a presigned upload URL (this endpoint)
  2. Upload your file to the returned upload_url using the method specified in upload_method
  3. POST /media/{id}/complete — Signal that the upload is finished

Upload methods by type:

  • Images — POST multipart-form to Cloudflare Images (field name: file)
  • Videos — PUT to R2 presigned URL with Content-Type header
  • Documents — PUT to R2 presigned URL with Content-Type header

Request Body Schema​

POST /media/upload — Content-Type: application/json

FieldTypeRequiredDescription
filenamestringYesOriginal filename with extension (max 255 chars). Example: photo.jpg
content_typestringYesMIME type of the file (see supported types below)
sizeintegerYesFile size in bytes. Max 20MB for images/documents, 500MB for video.
widthintegerNoImage/video width in pixels (used for aspect ratio calculation)
heightintegerNoImage/video height in pixels (used for aspect ratio calculation)
durationnumberNoVideo duration in seconds

Supported content types​

MIME TypeCategory
image/jpegImage
image/pngImage
image/gifImage
image/webpImage
image/heicImage
image/heifImage
video/mp4Video
application/pdfDocument

Request Example​

{
  "filename": "product-photo.jpg",
  "content_type": "image/jpeg",
  "size": 2048576
}

Response Example​

201 — Upload URL generated​

{
  "data": {
    "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "upload_url": "https://upload.imagedelivery.net/abc123/def456",
    "upload_method": {
      "method": "POST",
      "content_type": "multipart/form-data",
      "field_name": "file"
    },
    "provider": "cloudflare_images",
    "expires_in": 3600,
    "max_size": 20971520,
    "next_step": "Upload your file to upload_url, then call POST /media/{media_id}/complete to finalize."
  },
  "error": null,
  "meta": {
    "request_id": "a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

Response fields​

FieldTypeDescription
media_idstring (UUID)Use this ID when calling POST /media/{id}/complete and when attaching to posts via media_ids
upload_urlstringPresigned URL to upload your file to
upload_method.methodstringHTTP method to use: PUT or POST
upload_method.content_typestringContent-Type header to set
upload_method.field_namestringForm field name (only for POST/multipart uploads)
upload_method.headersobjectHeaders to include with the upload request (for PUT uploads)
providerstringStorage provider: cloudflare_images or r2
expires_inintegerSeconds until the upload URL expires
max_sizeintegerMaximum file size in bytes
next_stepstringInstructions for what to do after uploading

Request​

Responses​

Upload URL generated