Uploading media

Stream large files, or inline small ones as base64.

There are two ways to attach media to a post. Pick by size.

	Streaming upload	Inline base64
How	PUT /socials/media/{projectId}/stream-upload, then pass the handle	mediaItems on the create-post body
Good for	Video, anything over a few MB	Small images
Limit	10 MB images, 100 MB video	Bounded by request memory — keep it small

Default to the streaming upload. Base64 inflates a payload by about a third and the whole thing has to be held in memory at once, so it stops working well before the documented size limits.

Streaming upload

Send the raw bytes as the request body with the file’s own Content-Type. Not multipart, not base64 — the bytes themselves.

cURL

curl -X PUT \
  "https://api.sapt.ai/socials/media/$PROJECT_ID/stream-upload?filename=reel.mp4" \
  -H "Authorization: ApiKey $SAPT_API_KEY" \
  -H "Content-Type: video/mp4" \
  --data-binary @reel.mp4

Response

{
  "success": true,
  "data": {
    "handle": { "stagingId": "stg_01JQ…", "ext": "mp4" },
    "preview": {
      "r2Url": "https://assets.sapt.ai/staging/stg_01JQ….mp4",
      "contentType": "video/mp4",
      "sizeBytes": 18446721
    }
  }
}

Pass the whole handle object — both fields — in uploadedHandles when you create the post:

{
  "socialAccountId": "9f1c2f7a-…",
  "platform": "instagram",
  "mediaType": "REELS",
  "caption": "Behind the scenes.",
  "uploadedHandles": [{ "stagingId": "stg_01JQ…", "ext": "mp4" }],
  "scheduledFor": "2026-09-10T15:00:00Z",
  "timezone": "America/New_York"
}

preview.r2Url is a real URL you can show in a composer before the post exists. It is a staging location, not the published permalink.

Inline base64

For small images, skip the upload round trip:

{
  "socialAccountId": "9f1c2f7a-…",
  "platform": "instagram",
  "mediaType": "IMAGE",
  "caption": "Morning light.",
  "mediaItems": [
    {
      "base64": "iVBORw0KGgoAAAANSUhEUg…",
      "filename": "morning.jpg",
      "mimeType": "image/jpeg"
    }
  ],
  "publishNow": true
}

Send the base64 payload only — no data:image/jpeg;base64, prefix.

Carousels

Order is the order you supply. Sources are concatenated as uploadedHandles then mediaItems, so don’t split one carousel across both unless you want that ordering.

{
  "mediaType": "CAROUSEL",
  "uploadedHandles": [
    { "stagingId": "stg_a…", "ext": "jpg" },
    { "stagingId": "stg_b…", "ext": "jpg" },
    { "stagingId": "stg_c…", "ext": "jpg" }
  ]
}

Video covers

Pass coverImage to choose a video’s thumbnail. Same base64 shape as mediaItems:

{
  "mediaType": "REELS",
  "uploadedHandles": [{ "stagingId": "stg_01JQ…", "ext": "mp4" }],
  "coverImage": {
    "base64": "iVBORw0KGgo…",
    "filename": "cover.jpg",
    "mimeType": "image/jpeg"
  }
}

Validation

Media is checked against the target platform and mediaType before the post is accepted — dimensions, duration, file size, and count. A rejection comes back as 400 naming the offending item:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Media 2: video must be at most 60 seconds for STORIES"
  }
}

Removing media from a post

While a post is still editable, drop one item without touching the rest:

curl -X DELETE \
  "https://api.sapt.ai/socials/posts/$PROJECT_ID/$POST_ID/media/$MEDIA_ID" \
  -H "Authorization: ApiKey $SAPT_API_KEY"

mediaId comes from the media[] array on the post. This deletes the stored blob as well as the row.