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.
| Field | Type | Required | Description |
|---|---|---|---|
| filename | string | Yes | Name of the file (e.g. "photo.jpg") |
| mimeType | string | Yes | MIME type of the file (e.g. "image/jpeg", "video/mp4") |
Only image/* and video/* MIME types are allowed.
| Type | Formats |
|---|---|
| Images | JPEG, PNG, GIF, WebP |
| Videos | MP4, MOV |
Check mimeType against the actual file before requesting an upload URL.
| Platform | Container | Video and audio | Frame rate | Dimensions and aspect ratio | Duration | Maximum file size | Official specifications |
|---|---|---|---|---|---|---|---|
| TikTok | MP4 recommended; MOV and WebM supported | H.264 recommended; H.265, VP8, and VP9 supported | 23-60 FPS | Width and height must each be 360-4,096 px | Creator-specific; API upload maximum is 10 minutes | 4 GB | TikTok media transfer guide |
| Instagram Reel | MP4 or MOV | H.264 or HEVC; AAC, 48 kHz | 23-60 FPS | 0.01:1-10:1 required; 9:16 recommended; maximum 1,920 px wide | 3 seconds-15 minutes | 300 MB | Meta's Instagram Reel specifications |
| Facebook Page video | MP4 or MOV recommended | H.264 video with AAC audio recommended | 30 FPS or lower recommended | Maximum 4,000 px wide; dimensions divisible by 16 recommended | Up to 240 minutes | 4 GB | Facebook video settings and upload limits |
| YouTube video | MP4 recommended; YouTube accepts MOV, AVI, WebM, ProRes, HEVC, and other formats | H.264 video with AAC-LC audio recommended | Preserve the source frame rate; 24, 25, 30, 48, 50, and 60 FPS are common | 16:9 standard; player adapts to vertical and square video | 15 minutes by default; up to 12 hours for verified accounts | 256 GB | YouTube encoding settings and upload limits |
| YouTube Short | Same as YouTube video | Same as YouTube video | Same as YouTube video | Square or vertical | Up to 3 minutes | 256 GB | Three-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.
| Field | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | The 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.
| Code | Meaning |
|---|---|
| 200 | Upload URL generated |
| 400 | Unsupported MIME type or missing fields |
Check 400 responses for missing filename or mimeType and for unsupported MIME types.
POST {{API_BASE_URL}}/v1/media/uploadcurl -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"
}'curl -X PUT "UPLOAD_URL_FROM_RESPONSE" \
-H "Content-Type: image/png" \
--data-binary @launch-banner.pngDELETE {{API_BASE_URL}}/v1/media{
"success": true,
"freedBytes": 134868
}{
"success": true,
"data": {
"uploadUrl": "https://s3.amazonaws.com/bucket/...",
"publicUrl": "{{MEDIA_BASE_URL}}/uploads/.../launch-banner.png"
}
}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 -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"
}'