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	No size check at upload. The platform’s own limits apply when it publishes.	10 MB per image, 100 MB per video, and bounded by request memory, so 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 (image/* or video/*). 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, with 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

The item count is checked for every post before it is accepted (for example, an Instagram carousel takes 2 to 10 items). Inline mediaItems are also checked against the target platform and mediaType (dimensions, duration, and file size). 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"
  }
}

Streamed files are not inspected when you create the post. If the platform rejects one, the post moves to failed and errorMessage says why.

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 removes the attachment and deletes its stored file when the file belongs to that post. An attachment that references the asset library is removed, but the library file stays. For a clip pipeline that removes files after publication, see Media retention and cleanup.

Start with the API

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