Media uploads

Posts carry an ordered media array. Each item names where the media comes from with source_type, so one list can mix an uploaded file, a public URL, and media you uploaded to a platform yourself. Order is preserved and decides carousel sequence.

`source_type`	`source` is	Use it when
`media_id`	A media library UUID from an upload	You uploaded the file to SocialAPI (see below)
`url`	A public `http(s)` URL	The file is already hosted somewhere public and you do not want to upload it
`platform_attachment_id`	A media ID from the target platform’s own API	You uploaded to the platform directly and want to publish it without re-upload

{
  "text": "Behind the scenes from our studio shoot.",
  "media": [
    { "source_type": "media_id", "source": "f47ac10b-58cc-4372-a567-0e02b2c3d479" },
    { "source_type": "url", "source": "https://cdn.example.com/photo.jpg" }
  ],
  "targets": [{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }]
}

The older media_ids array still works and is not going away without notice. ["abc"] is exactly equivalent to [{ "source_type": "media_id", "source": "abc" }]. If you send both, media wins and media_ids is ignored. Responses continue to include media_ids alongside media, listing the media_id items only.

Uploading and verifying media does not cost credits. A credit is charged only when the post publishes or is scheduled.

Choosing an upload path

There are two ways to get a file into SocialAPI. Both return a media_id that you use the same way.

	Server-side upload	Presigned URL
Endpoint(s)	`POST /v1/media/upload`	`GET /v1/media/upload-url`, then `PUT`, then `POST /v1/media/{id}/verify`
Calls	One	Three
Max file size	50 MB	No API limit (plan storage quota applies)
Best for	Small files, or clients that cannot reach S3 directly (for example AI sandboxes)	Large files, especially video

If a file is larger than 50 MB, use the presigned-URL path.

Server-side upload

Send the file as multipart form data in a single request. The file field is required.

curl -X POST https://api.social-api.ai/v1/media/upload \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -F "file=@photo.jpg"

Response:

{
  "media_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

The returned media is immediately ready. Pass it as a media_id source on your next POST /v1/posts call (see Using media in posts).

Presigned URL upload

Use this path for large files. It has three steps: request a signed URL, upload the bytes to it, then verify. Step 1: Request a signed upload URL. Both media_type (the file’s MIME type) and filename are required.

curl "https://api.social-api.ai/v1/media/upload-url?media_type=video/mp4&filename=reel.mp4" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response:

{
  "media_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "upload_url": "https://storage.example.com/media/...?X-Amz-Signature=...",
  "expires_at": "2026-07-07T09:15:00Z"
}

The upload_url is valid for 15 minutes. Step 2: Upload the file with an HTTP PUT to upload_url. The Content-Type must match the media_type you declared in step 1.

curl -X PUT "https://storage.example.com/media/...?X-Amz-Signature=..." \
  -H "Content-Type: video/mp4" \
  --data-binary @reel.mp4

Step 3: Verify the upload. This step is required. It confirms the bytes landed, records the file size, and flips the media from pending to ready.

curl -X POST https://api.social-api.ai/v1/media/f47ac10b-58cc-4372-a567-0e02b2c3d479/verify \
  -H "Authorization: Bearer $SOCAPI_KEY"

If you skip verification, the media stays pending and publishing fails with Media not found.

Using media in posts

Pass the media array on POST /v1/posts. Order is preserved. A single entry produces an image or video; multiple entries produce a carousel, subject to each platform’s limits.

curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }],
    "text": "Behind the scenes from our studio shoot.",
    "media": [
      { "source_type": "media_id", "source": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }
    ]
  }'

media is also accepted per target, where it overrides the post-level list for that platform only. A target that sets no media inherits the post-level one. Per-platform media limits (image versus video, carousel counts, maximum items per post) are listed in the Posts overview capability matrix.

Publishing from a public URL

Set source_type to url and we fetch the file at publish time. Nothing is stored in your media library and no storage quota is consumed.

{
  "media": [
    { "source_type": "url", "source": "https://cdn.example.com/photo.jpg" }
  ]
}

The URL must be publicly reachable over http or https. URLs resolving to private, loopback, link-local, or otherwise internal addresses are rejected. The check runs again at publish time, so a URL that stops resolving publicly between scheduling and publishing fails the post rather than silently dropping the media. Because the fetch happens when the post publishes, the URL must still be live at that moment. For a post scheduled weeks out, an uploaded media_id is the safer choice: a link that expires or rotates in the meantime will fail the post.

Publishing a platform attachment ID

If you have already uploaded media to a platform through its own API, pass that ID directly and we publish it without re-uploading.

{
  "media": [
    { "source_type": "platform_attachment_id", "source": "18234567890123456", "type": "image" }
  ]
}

type is required here (image, video, audio, or file). For url and media_id we infer it from the file, but a platform attachment ID is opaque to us, so you have to declare it. Supported on Instagram, Threads, LinkedIn, LinkedIn Page, and X/Twitter. Any other platform returns 422 publishing.media.unsupported_source. Mixing rules differ by platform:

Platform	Can mix an attachment ID with other media?
LinkedIn, LinkedIn Page, X/Twitter	Yes, combine freely with `url` and `media_id` items
Instagram, Threads	No. The attachment must be the only item in `media`

On Instagram and Threads a platform_attachment_id is one finished, publishable container (a single photo or video, or a carousel you assembled yourself), so it cannot be combined with anything else. Sending more than one item returns 422 publishing.media.mixing_unsupported. To build a mixed carousel there, pass url or media_id items and we assemble it for you. These gates are per target: a post can still publish to its other targets when one target is rejected.

Managing your library

List media. Returns your ready files, newest first, with cursor pagination (default 50 per page, max 100). Each item includes a short-lived url for previewing the file.

curl "https://api.social-api.ai/v1/media?limit=50" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Delete media.

curl -X DELETE https://api.social-api.ai/v1/media/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer $SOCAPI_KEY"

Check storage usage. Returns bytes used, the plan limit, and file count. The same values come back as X-Storage-Used and X-Storage-Limit response headers on media requests (-1 means unlimited).

curl https://api.social-api.ai/v1/media/storage \
  -H "Authorization: Bearer $SOCAPI_KEY"

{
  "used_bytes": 52428800,
  "limit_bytes": 104857600,
  "count": 12
}

Storage limits

Plan	Storage
Free	100 MB
Starter, Pro, Business, Enterprise	Unlimited

An upload that would exceed your quota returns 413. On the presigned path the object is removed and the media is marked failed.

Constraints and gotchas

A public URL now publishes directly as a url source. In the deprecated media_ids array a raw URL is still ignored: media_ids only accepts media library IDs.
url sources are fetched at publish time and must still be reachable then. Prefer an uploaded media_id for posts scheduled far ahead.
platform_attachment_id requires an explicit type, works only on Instagram, Threads, LinkedIn, LinkedIn Page, and X/Twitter, and cannot be mixed with other media on Instagram or Threads.
The verify step is mandatory on the presigned path. Without it, media stays pending and publishing fails with Media not found.
The server-side upload endpoint caps files at 50 MB. Use the presigned path for anything larger.
Media has three states: pending (created, bytes not yet confirmed), ready (usable in posts), and failed (quota exceeded, or the object was missing at verify).
Video duration is detected automatically at verify or upload time. You do not need to send it.
Per-platform format, size, and count rules are enforced when you publish. See each platform’s posts page.

Getting Started

Core Concepts

Choosing an upload path

Server-side upload

Presigned URL upload

Using media in posts

Publishing from a public URL

Publishing a platform attachment ID

Managing your library

Storage limits

Constraints and gotchas

​Choosing an upload path

​Server-side upload

​Presigned URL upload

​Using media in posts

​Publishing from a public URL

​Publishing a platform attachment ID

​Managing your library

​Storage limits

​Constraints and gotchas

Choosing an upload path

Server-side upload

Presigned URL upload

Using media in posts

Publishing from a public URL

Publishing a platform attachment ID

Managing your library

Storage limits

Constraints and gotchas