Posts
Upload large videos to use in posts via API
Posts take media by URL. If you have nowhere to host the file, send it to Connect and get a URL on a domain the networks accept. Up to 8 MB goes in a single request; above that, the video is uploaded in parts, up to 1 GB, and you use the URL in media.url of POST /posts.
The request
POST /api/media/uploads
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"file_name": "reels-summer.mp4",
"size": 52428800
}What you can do
- Upload a file of up to 8 MB in a single request with POST /media.
- Open an upload in parts with POST /media/uploads for files of up to 1 GB.
- Send the parts with PUT /media/uploads/{uuid}/parts/{part}, in parallel after part 1.
- Resume an interrupted upload: GET /media/uploads/{uuid} tells you which parts have arrived.
- Finish with POST /media/uploads/{uuid}/complete and get the URL ready to use in a post.
Rules and limits
- POST /media takes up to 8 MB. Above that it responds 413 media_too_large_for_single_upload and the upload goes in parts.
- Connect reads the file type from part 1. Part 1 goes first; the others can go in any order and at the same time. Resending a part replaces the previous one.
- Each part requires a Content-Length equal to its exact size (upload.part_size, or the remainder on the last one). Without it, the response is 411.
- It accepts JPEG, PNG, WebP and GIF (images up to 30 MB), MP4 and MOV (up to 1 GB). The type comes from the content, not the name, and the whole file is checked on completion (422 media_content_invalid if it is not valid).
- The URL is valid until expires_at, 30 days after the media becomes ready, and then the file is deleted. Anyone with the link can read the file, so only pass it to whoever will publish.
- POST /media and POST /media/uploads require the Idempotency-Key header. Up to 20 open uploads per customer.
Main fields
| Field | Type | Required | Description |
|---|---|---|---|
| file_name | string | Yes | The file name (up to 255 characters). |
| size | integer | Yes | The exact file size in bytes, from 1 up to 1073741824 (1 GB). |
| upload.part_size | integer | No | In the response: the bytes in each part. The last one carries the remainder. |
| upload.parts | integer | No | In the response: how many parts the file has, numbered from 1. |
| upload.expires_at | string | No | In the response: until when the upload can be completed. After that the parts are discarded. |
| received_parts | array | No | In GET /media/uploads/{uuid}: the parts already received, to resume an interrupted upload. |
| url | string | No | When status is ready: the public URL to use in media.url of POST /posts. |
| expires_at | string | No | When the URL stops being valid and the file is deleted: 30 days after the media becomes ready. |
Who it is for
Video editor SaaS
The user exports a 200 MB Reels; the product uploads it in parts and publishes to Instagram and Facebook using the returned URL.
Agency with heavy videos
The dashboard uploads the campaign videos once and reuses the same URL in posts across several networks.
Video AI agent
The agent generates a video, uploads it to Connect in parts and passes the URL to POST /posts without hosting anything.
Works with
Instagram Business
Facebook
YouTube
LinkedIn
Threads
Pinterest
Frequently asked questions
What is the maximum size?
Up to 8 MB in a single request (POST /media) and up to 1 GB in parts (POST /media/uploads). Images are limited to 30 MB.
How long does the URL stay up?
30 days from when the media becomes ready. After that the file is deleted, so use the URL in a post within that window.
What happens if the upload drops midway?
Call GET /media/uploads/{uuid}: received_parts lists the parts received. Send only the missing ones and complete. The upload stays open until upload.expires_at.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
