Skip to content

Upload Media API

The Upload Media API lets you upload images and videos for use in social posts without sending large binary files through the main API. You request a presigned S3 URL, upload the file directly to storage, and then reference the returned public URL when you create a post. This page covers the exact request and response fields, the three-step upload flow, supported formats, per-platform video specifications, deletion, and the status codes you need to check.

Overview and three-step presigned S3 flow

The Upload Media API provides presigned S3 URLs for media uploads. The flow has three steps. First, request a presigned upload URL. Second, upload the file directly to S3 using that presigned URL. Third, use the returned public URL in your post's mediaItems. Keeping the binary transfer separate from the post-creation request means you can check the upload result before you publish, and you can reuse the same publicUrl value in the post payload without embedding file data in JSON.

Get Upload URL: POST {{API_BASE_URL}}/v1/media/upload

Call POST {{API_BASE_URL}}/v1/media/upload to get an upload URL. Send the x-access-key header with your API key and Content-Type: application/json. The request body requires filename as a string, for example photo.jpg, and mimeType as a string, for example image/jpeg or video/mp4. Only image/* and video/* MIME types are allowed. If you omit either field or send an unsupported MIME type, expect a 400 response, so validate both fields on the client before calling the endpoint. The successful response returns success as true and a data object containing uploadUrl, the presigned S3 URL for the PUT step, and publicUrl, the URL you will later place in mediaItems. Save both values from the same response; do not construct either URL yourself.

Upload the File to S3

Use the uploadUrl from the response to upload the file directly. Send a PUT request to that exact URL with a Content-Type header matching the file, such as image/png, and send the file bytes as the binary body. The example in the code section uses curl with --data-binary and a local file path as a placeholder. Check that the PUT succeeds before creating a post. If the PUT fails, the publicUrl will not point to a usable file, so treat a failed PUT as a stop condition and do not proceed to post creation; as a client-side recommendation, you may request a fresh upload URL and retry the PUT rather than reusing the failed attempt.

Use in a Post with mediaItems

After uploading, use the publicUrl as the media URL in your post. In the post-creation request, add an entry to mediaItems with type set to image and url set to the publicUrl returned by the upload step, as shown in the worked example. The example creates a post with content, a platforms array containing a platform and accountId, a mediaItems array containing the uploaded image, and publishNow set to true. Verify that the url value matches the publicUrl character for character, including the path, before sending the post request.

Supported Formats

Supported image formats are JPEG, PNG, GIF, and WebP. Supported video formats are MP4 and MOV. Choose the format before you request the upload URL, because mimeType must reflect the actual file you will PUT to the presigned S3 URL. When the same clip needs to work across several destinations, an MP4 file encoded with H.264 video with AAC audio, progressive scanning, and its moov atom placed near the start tends to be the safest starting point.

Video Specifications by Platform

Destination limits shift over time and can differ by account, so treat the specifications in the table as planning guidance and check the linked official specifications for the destination platform before publishing large or long videos. On TikTok, read maxVideoPostDurationSec from the creator-info response and plan around that account-specific duration rather than assuming a 10-minute allowance for every creator. Compare container, codec, frame rate, dimensions, duration, and maximum file size for each destination before encoding, because a file that uploads successfully can still exceed a destination platform limit.

Delete Media: DELETE {{API_BASE_URL}}/v1/media

You can permanently delete a media file you uploaded. Deletion removes it from storage and frees that space from your project's storage usage. Call DELETE {{API_BASE_URL}}/v1/media with the x-access-key header and Content-Type: application/json. The request body requires url as a string, which must be the publicUrl returned by /v1/media/upload and must belong to your project. The response returns success as true and freedBytes, which is how many bytes were freed from your project's storage usage. Record freedBytes after deletion if you track storage usage, and do not reuse the deleted publicUrl in later posts.

Status Codes and failure matrix

A 200 response means the upload URL was generated. A 400 response means an unsupported MIME type or missing fields. Use these codes as your first failure check: if you receive 400, confirm that filename and mimeType were both present and that mimeType starts with image/ or video/. For video publishing failures after a successful upload, check the per-platform specifications in the table, including container, codec, frame rate, dimensions, duration, and maximum file size.

Get Upload URL request body
FieldTypeRequiredDescription
filenamestringYesName of the file (e.g. "photo.jpg")
mimeTypestringYesMIME type of the file (e.g. "image/jpeg", "video/mp4")

Only image/* and video/* MIME types are allowed.

Supported Formats
TypeFormats
ImagesJPEG, PNG, GIF, WebP
VideosMP4, MOV

Check mimeType against the actual file before requesting an upload URL.

Video Specifications by Platform
PlatformContainerVideo and audioFrame rateDimensions and aspect ratioDurationMaximum file sizeOfficial specifications
TikTokMP4 recommended; MOV and WebM supportedH.264 recommended; H.265, VP8, and VP9 supported23-60 FPSWidth and height must each be 360-4,096 pxCreator-specific; API upload maximum is 10 minutes4 GBTikTok media transfer guide
Instagram ReelMP4 or MOVH.264 or HEVC; AAC, 48 kHz23-60 FPS0.01:1-10:1 required; 9:16 recommended; maximum 1,920 px wide3 seconds-15 minutes300 MBMeta's Instagram Reel specifications
Facebook Page videoMP4 or MOV recommendedH.264 video with AAC audio recommended30 FPS or lower recommendedMaximum 4,000 px wide; dimensions divisible by 16 recommendedUp to 240 minutes4 GBFacebook video settings and upload limits
YouTube videoMP4 recommended; YouTube accepts MOV, AVI, WebM, ProRes, HEVC, and other formatsH.264 video with AAC-LC audio recommendedPreserve the source frame rate; 24, 25, 30, 48, 50, and 60 FPS are common16:9 standard; player adapts to vertical and square video15 minutes by default; up to 12 hours for verified accounts256 GBYouTube encoding settings and upload limits
YouTube ShortSame as YouTube videoSame as YouTube videoSame as YouTube videoSquare or verticalUp to 3 minutes256 GBThree-minute YouTube Shorts

Platform limits can change, and account-specific limits can be lower. For TikTok, use maxVideoPostDurationSec from the creator-info response instead of assuming a 10-minute maximum.

Delete Media request body
FieldTypeRequiredDescription
urlstringYesThe publicUrl returned by /v1/media/upload. Must belong to your project.

The url must be the publicUrl returned by /v1/media/upload and must belong to your project.

Status Codes
CodeMeaning
200Upload URL generated
400Unsupported MIME type or missing fields

Check 400 responses for missing filename or mimeType and for unsupported MIME types.

Get Upload URL endpoint
POST {{API_BASE_URL}}/v1/media/upload
Request a presigned upload URL with curl
curl -X POST "{{API_BASE_URL}}/v1/media/upload" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "launch-banner.png",
    "mimeType": "image/png"
  }'
Upload the file to the presigned S3 URL
curl -X PUT "UPLOAD_URL_FROM_RESPONSE" \
  -H "Content-Type: image/png" \
  --data-binary @launch-banner.png
Delete Media endpoint
DELETE {{API_BASE_URL}}/v1/media
Delete Media response
{
	"success": true,
	"freedBytes": 134868
}
Get Upload URL response
{
	"success": true,
	"data": {
		"uploadUrl": "https://s3.amazonaws.com/bucket/...",
		"publicUrl": "{{MEDIA_BASE_URL}}/uploads/.../launch-banner.png"
	}
}
cURL request 7
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" }
    ],
    "mediaItems": [
      { "type": "image", "url": "{{MEDIA_BASE_URL}}/uploads/.../launch-banner.png" }
    ],
    "publishNow": true
  }'
cURL request 9
curl -X DELETE "{{API_BASE_URL}}/v1/media" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "{{MEDIA_BASE_URL}}/uploads/.../launch-banner.png"
  }'