Media Upload

Uploading Files

Upload a local file and receive a URL you can use in posts:

postiz upload <file-path>

The command returns a JSON response with the uploaded file’s URL:

{
  "id": "img-123",
  "path": "https://uploads.postiz.com/your-file.jpg"
}

You must upload media files to Postiz before using them in posts. Many platforms (TikTok, Instagram, YouTube) require verified URLs and will reject external links.

Adjusting Media to Platform Limits

Platforms reject media that is too large, too small or in an encoding they don’t accept. Add --adjust (off by default) to adjust the file after the upload: videos are scaled to 1080p and re-encoded to MP4, oversized images are scaled down. See Upload File for the details.

postiz upload video.mp4 --adjust
postiz media:status <id>

The status is processing until the adjusted file replaces the original at the same path, usually within seconds. Poll media:status and wait until it is ready before publishing a post with this path: a post published while it is processing uses the original, unadjusted file. If the adjustment fails, the original file is kept and used for publishing, and the status is ready with a warning.

Upload and Post Workflow

# 1. Upload the file
RESULT=$(postiz upload photo.jpg)
FILE_URL=$(echo "$RESULT" | jq -r '.path')

# 2. Use the URL in a post
postiz posts:create \
  -c "Check out this photo!" \
  -m "$FILE_URL" \
  -s "2025-01-15T10:00:00Z" \
  -i "your-integration-id"

Supported File Types

Images
Videos
Audio
Documents

PNG, JPG, JPEG, GIF, WEBP, SVG, BMP, ICO

Video Upload Example

Platforms like TikTok, YouTube, and Instagram require video uploads through Postiz:

# Upload the video
VIDEO=$(postiz upload video.mp4)
VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')

# Post to TikTok
postiz posts:create \
  -c "New video! #fyp" \
  -m "$VIDEO_URL" \
  -s "2025-01-15T10:00:00Z" \
  --settings '{"privacy_level":"PUBLIC_TO_EVERYONE"}' \
  -i "tiktok-integration-id"

privacy_level and the other TikTok settings apply only when content_posting_method is "DIRECT_POST", with "UPLOAD" (send to the TikTok app inbox instead of publishing) TikTok keeps only the post content.

CLI

MCP

Uploading Files

Adjusting Media to Platform Limits

Upload and Post Workflow

Supported File Types

Video Upload Example

​Uploading Files

​Adjusting Media to Platform Limits

​Upload and Post Workflow

​Supported File Types

​Video Upload Example

Uploading Files

Adjusting Media to Platform Limits

Upload and Post Workflow

Supported File Types

Video Upload Example