Skip to content
API-governed Images Videos URL rules

Social Media Specifications

Quickly navigate API-driven image, video, document, aspect ratio, URL, and media constraints across all supported publishing platforms.

API rules are the source of truth
A post that works in the app can still fail via API. Postly validates media against platform API constraints.
Use stable, public media URLs
Bulk publishing fails most often because of bad links. Use Postly Cloud or a public CDN for direct image/video URLs.
Use recommended aspect ratios
Safe recommendations reduce rejections, processing errors, and ugly crops across platforms.
Read this first

Media URL format rules

These rules prevent most API upload failures, especially for Bulk Post via CSV or Google Sheets.

Best practice: use Postly Cloud for stable public URLs.
Image URL format rules
Examples that work
  • https://upload.wikimedia.org/wikipedia/commons/9/9a/Gull_portrait_ca_usa.jpg
  • https://cloud.postly.ai/media/your-image.jpg
  • https://static.cdn.example.com/banner-v3.png
Examples to avoid
  • https://www.instagram.com/p/XXXXXXXXX/
  • https://photos.google.com/share/XXXX
  • data:image/png;base64,iVBORw0K...
  • https://www.dropbox.com/s/FILE_ID/photo.png?dl=0
Use direct, public image file links (jpg/png/gif). Avoid links that require login, “share pages”, or base64 data URLs.
Video URL format rules
Examples that work
  • https://www.youtube.com/watch?v=dQw4w9WgXcQ
  • https://youtu.be/dQw4w9WgXcQ
  • https://vimeo.com/76979871
  • https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4
  • https://cloud.postly.ai/media/your-video.mp4
Examples to avoid
  • https://youtube.com/shorts/XXXXXXXXXXX
  • https://www.youtube.com/watch?v=dQw4w9WgXcQ&list=PL123456789
  • https://drive.google.com/file/d/FILE_ID/view?usp=share_link
  • https://www.dropbox.com/s/FILE_ID/video.mp4?dl=0
Use direct/public links or supported sources (YouTube watch / youtu.be, Vimeo, direct .mp4). Avoid Shorts URLs, playlist URLs, and private hosts like Drive/Dropbox share links.

Instagram

These limits are enforced by the platform API. Your post must comply to publish successfully.

ImagesVideoAPI constraintsRecommended
API docs
Why this matters
Instagram’s API can be stricter than the Instagram app. Postly follows the API rules to publish reliably across accounts and business permissions.
API-safe recommendations
Square 1:1 (1080×1080)Portrait 4:5 (1080×1350)Vertical 9:16 (Stories/Reels)JPEG for imagesMP4 for video

Images

API

• API-safe max size: ~8MB

• Aspect ratios: 1:1, 4:5, 9:16 depending on placement

• Most reliable: JPEG

• Carousels: multiple images supported (API-enforced limits)

Video

API

• Most reliable: MP4 (H.264 + AAC)

• Reels/Stories: vertical 9:16 preferred

• Keep duration within the post type limits (API-enforced)

Text

API

• Captions are API-limited

• Hashtag stuffing can reduce reach (and may trigger moderation)

Important Note
Using PNGs/GIFs where the API expects JPEG can fail
Important Note
Incorrect aspect ratio for the chosen media type (Reels/Stories want vertical)
Important Note
Oversized files / slow hosts can time out during ingestion
Need help? Visit docs.postly.ai or use Bulk Post via Google Sheets for validations and guided uploads.