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"
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_idPOST /media/storage/chunk — send 1 MB chunksPOST /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.
| 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 | 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"}'
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