Publishing with Media
Attach media to posts using the
media object in Create Post.
Media fields:
- Images: "media": { "images": ["https://..."] } — one or more image URLs
- Video: "media": { "video": "https://..." } — single video URL
- PDF carousel: "media": { "carousel": "https://..." } — LinkedIn only
Where to get media URLs:
Option A — Use any publicly accessible HTTPS URL. No upload step needed. Works for all platforms except TikTok (TikTok requires URLs hosted on our domain).
Option B — Upload via the [Upload Media](/docs/api/upload-media) endpoint. Accepts images, videos, and PDFs up to 100 MB. Returns a hosted URL ready to use.
Auto-processing: PostHero automatically compresses or converts images that exceed a platform's size limit before publishing. Threads images over 8 MB are compressed to JPEG. TikTok images are resized to 1080px and converted to JPEG if needed. This avoids publish failures but may reduce image quality — for best results, stay within the limits below.
Platform media limits| Platform | Images | Video | Notes |
|---|---|---|---|
| JPG, PNG, GIF · up to 9 · max 5 MB each | MP4 · max 5 GB · 3 sec – 10 min | PDF carousel via media.carousel (up to 300 pages, max 100 MB) | |
| twitter/x | JPG, PNG, GIF, WebP · up to 4 · max 5 MB each (GIF: max 15 MB) | MP4 · max 512 MB · max 140 sec | |
| threads | JPG, PNG · up to 10 · max 8 MB each | MP4 · max 100 MB · max 5 min | Images over 8 MB are auto-compressed to JPEG before publishing |
| JPG, PNG · up to 10 in carousel · max 8 MB each | MP4 · max 1 GB · 3–90 sec (Reels) | contentType controls feed / reel / story / carousel | |
| bluesky | JPG, PNG, WebP, GIF · up to 4 · max 1 MB each | — | |
| tiktok | JPEG, WebP · up to 35 · max 20 MB · max 1080px | MP4 · max 4 GB (PostHero upload limit: 100 MB) | Images auto-converted to JPEG and resized if they exceed limits. Carousels require URLs from Upload Media endpoint. |
| JPG, PNG · max 4 MB each | MP4 · max 4 GB · max 240 min | ||
| youtube | — | MP4 · max 256 GB / 12 hrs (PostHero: 100 MB via upload) | Requires title via platformContent.youtube.title |
Example request
// Step 1: Upload
curl --request POST \
--url https://server.posthero.ai/api/v1/media/upload \
--header 'Authorization: Bearer YOUR_API_KEY' \
--form 'file=@/path/to/image.png'
// Response: { "data": { "url": "https://s3.amazonaws.com/..." } }
// Step 2: Create post with the uploaded image
curl --request POST \
--url https://server.posthero.ai/api/v1/posts \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"text": "Check this out!",
"platforms": [{ "platform": "linkedin", "accountId": "abc123" }],
"media": { "images": ["https://s3.amazonaws.com/..."] },
"publishNow": true
}'