> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postqueen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Media Upload

> Upload images, videos, and other media files for use in posts

Media has to live on a PostQueen domain before she can attach it, so every image and video goes through her first.

## Uploading Files

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

```bash theme={"system"}
postqueen upload <file-path>
```

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

```json theme={"system"}
{
  "id": "img-123",
  "path": "https://uploads.postqueen.ai/your-file.jpg"
}
```

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

## Upload and Post Workflow

```bash theme={"system"}
# 1. Upload the file (tail -n +2 drops the header line, which is not JSON)
IMG=$(postqueen upload photo.jpg | tail -n +2 | jq -r '.path')

# 2. Use the URL in a post
postqueen posts:create \
  -c "Check out this photo!" \
  -m "$IMG" \
  -s "2026-08-01T09:00:00Z" \
  -i "your-integration-id"
```

## Supported File Types

The API inspects the file's bytes rather than its extension, and accepts:

* **Images:** JPEG, PNG, GIF, WebP, AVIF, BMP, TIFF (10 MB cap)
* **Video:** MP4 (1 GB cap)

Anything else returns `Unsupported file type.`

<Warning>
  Only `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` and `.mp4` paths can be attached to a post. AVIF, BMP and TIFF upload successfully and are then rejected by `posts:create` with `File must have a valid extension`. Convert those before uploading.
</Warning>

## Video Upload Example

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

```bash theme={"system"}
# Upload the video
VIDEO_URL=$(postqueen upload video.mp4 | tail -n +2 | jq -r '.path')

# Post to TikTok
postqueen posts:create \
  -c "New video! #fyp" \
  -m "$VIDEO_URL" \
  -s "2026-08-01T09:00:00Z" \
  --settings '{"content_posting_method":"DIRECT_POST","privacy_level":"PUBLIC_TO_EVERYONE","duet":true,"stitch":true,"comment":true,"autoAddMusic":"no","brand_content_toggle":false,"brand_organic_toggle":false}' \
  -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.