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

FieldTypeRequiredDescription
file_namestringYesThe file name (up to 255 characters).
sizeintegerYesThe exact file size in bytes, from 1 up to 1073741824 (1 GB).
upload.part_sizeintegerNoIn the response: the bytes in each part. The last one carries the remainder.
upload.partsintegerNoIn the response: how many parts the file has, numbered from 1.
upload.expires_atstringNoIn the response: until when the upload can be completed. After that the parts are discarded.
received_partsarrayNoIn GET /media/uploads/{uuid}: the parts already received, to resume an interrupted upload.
urlstringNoWhen status is ready: the public URL to use in media.url of POST /posts.
expires_atstringNoWhen 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.

Related

See everything you can do with Posts

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.