Media Guidelines

Postsiva accepts images and videos through POST /media/upload. Use returned media_id values in post endpoints (default_image_id, video_id, image_ids). Full API reference: Media.

Upload flow

# Simple upload (< 10 MB)
curl -X POST "https://backend.postsiva.com/media/upload" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "media_type=image"

Response includes media_id — reference it in post bodies.

Large files (≥ 10 MB)

Use the chunked storage API (not query params on /upload):

POST /media/storage/init — get upload_id
POST /media/storage/chunk — send 1 MB chunks
POST /media/storage/complete — finalize and get media_id

Video processing after upload may take time for large files. The complete step uses an extended timeout.

Supported formats

Type	Formats
Image	JPEG, PNG, GIF, WebP
Video	MP4, MOV, AVI, MKV, WebM, M4V

General requirements

Rule	Detail
HTTPS URLs	External `default_image_url` / `video_url` must be `http` or `https`
Media ID vs URL	Prefer `media_id` or HTTPS `*_url` fields; Threads/Bluesky auto-upload URLs server-side
Carousel size	2–20 images (LinkedIn/Instagram); 2–5 for Pinterest carousel pins
Auto-fix	Postsiva letterboxes images to platform canvas sizes when normalization runs

Auto-fit canvas sizes

When image auto-fix runs, targets are:

Platform	Canvas (W × H)
LinkedIn	1080 × 1080
Facebook	1080 × 1350
Instagram	1080 × 1350 (aspect ratio corrected)
TikTok	1080 × 1920
Threads	1080 × 1920
Pinterest	1000 × 1500
Bluesky	1000 × 1000

Upload high-resolution source images. Auto-fix preserves content with letterboxing rather than cropping arbitrarily.

Platform-specific notes

Platform	Key requirement	Doc
Instagram	4:5 to 1.91:1 aspect ratio; Reels video	Instagram
TikTok	9:16 video preferred	TikTok
YouTube	Title required; optional custom thumbnail	YouTube
Pinterest	`board_id` + image or video	Pinterest
Bluesky	`default_image_id` or `default_image_url`; video id or URL	Bluesky
Threads	`default_image_id` or `default_image_url`	Threads
Facebook	Per-page images via `facebook_page_images`	Facebook
LinkedIn	Per-page images via `linkedin_page_images`	LinkedIn

Post body media fields

Field	Use
`default_image_id`	Single image (most platforms)
`default_image_url`	Direct URL (platforms that support pull-from-URL)
`image_ids`	Carousel — array of media IDs
`video_id`	Uploaded video media ID
`video_url`	Direct video URL (where supported)

Example: multi-platform image post

{
  "platforms": ["linkedin", "instagram", "facebook"],
  "default_text": "Product launch visual.",
  "default_image_id": "uploaded-media-uuid",
  "facebook": {
    "facebook_page_ids": ["756356074224043"]
  }
}

AI-generated images

Generate images from text, then post:

curl -X POST "https://backend.postsiva.com/unified/image/generate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{"prompt": "Minimal product hero shot, white background"}'

Use returned media_id in a post request. Requires AI Composer on your plan.

Character limits

Caption and title limits

Scheduling

Schedule media posts

Media API

Upload, chunked storage, list, delete

Get started

Features

REST API

MCP

Platforms

Guides

Integrations

Errors

Reference

Upload flow

Large files (≥ 10 MB)

Supported formats

General requirements

Auto-fit canvas sizes

Platform-specific notes

Post body media fields

Example: multi-platform image post

AI-generated images

Character limits

Scheduling

Media API

​Upload flow

​Large files (≥ 10 MB)

​Supported formats

​General requirements

​Auto-fit canvas sizes

​Platform-specific notes

​Post body media fields

​Example: multi-platform image post

​AI-generated images

​Related

Character limits

Scheduling

Media API

Upload flow

Large files (≥ 10 MB)

Supported formats

General requirements

Auto-fit canvas sizes

Platform-specific notes

Post body media fields

Example: multi-platform image post

AI-generated images

Related