Uploading media

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 -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

import { createReadStream, statSync } from 'node:fs'

const res = await fetch(
  `https://api.sapt.ai/socials/media/${projectId}/stream-upload?filename=reel.mp4`,
  {
    method: 'PUT',
    headers: {
      Authorization: `ApiKey ${process.env.SAPT_API_KEY}`,
      'Content-Type': 'video/mp4',
      'Content-Length': String(statSync('reel.mp4').size),
    },
    body: createReadStream('reel.mp4'),
    duplex: 'half',
  }
)

const { data } = await res.json()
const handle = data.handle // → uploadedHandles on create-post

with open("reel.mp4", "rb") as f:
    res = requests.put(
        f"https://api.sapt.ai/socials/media/{project_id}/stream-upload",
        params={"filename": "reel.mp4"},
        headers={
            "Authorization": f"ApiKey {api_key}",
            "Content-Type": "video/mp4",
        },
        data=f,
    )
handle = res.json()["data"]["handle"]

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.

Get started

Platform

Social publishing

Analytics

REST API guides

MCP connector

Uploading media

Streaming upload

Inline base64

Carousels

Video covers

Validation

Removing media from a post

​Streaming upload

​Inline base64

​Carousels

​Video covers

​Validation

​Removing media from a post

Streaming upload

Inline base64

Carousels

Video covers

Validation

Removing media from a post