# YouTube API guide

> Upload a video or Short to YouTube with a title, tags, privacy, a playlist and a custom thumbnail. Platform key: youtube.

**Source:** https://postprism.app/docs/platforms/youtube  
**Updated:** 2026-10-10

---

|   |   |
| --- | --- |
| Platform key | `youtube` |
| Text limit | 5,000 characters (description); 100 (title) |
| Media | Required: one video. A post without a video fails with “YouTube posts need a video.” |

## Things to know

- `content` becomes the description. Without `settings.title`, the first line of the text is used as the title.
- YouTube has no hashtags field: hashtags you set for YouTube are added to the video’s tags instead.
- If the thumbnail or playlist step fails, the video stays published and the post shows a warning.

## Settings

Optional YouTube options go in `platform_content.youtube.settings`. Invalid values are rejected when you create or update the post, with a message naming the field.

| Field | Type | Description |
| --- | --- | --- |
| `title` | string, up to 100 characters | The video title. No `<` or `>`. |
| `tags` | string[] | Search tags, 500 characters in total. No commas or angle brackets. |
| `privacyStatus` | `"public"`, `"unlisted"`, `"private"` | Who can watch the video. |
| `madeForKids` | boolean | YouTube’s audience declaration. |
| `categoryId` | string | A YouTube category, for example `"22"` People & Blogs (default), `"27"` Education, `"28"` Science & Technology. |
| `containsSyntheticMedia` | boolean | `true` if the video contains realistic AI-altered or synthetic content. |
| `playlistId` | string | Add the video to one of your playlists. |
| `thumbnailUrl` | string | A custom thumbnail: a `url` from `POST /api/v1/media`. Converted to the size YouTube accepts. |

**platform_content.youtube**

```
"youtube": {
  "content": "A full walkthrough of our new roasting profile…",
  "settings": {
    "title": "How we roast our autumn blend",
    "privacyStatus": "public",
    "madeForKids": false,
    "categoryId": "26"
  }
}
```

## Example

**POST /api/v1/posts**

```
{
  "base_content": "Our autumn menu is here.",
  "platforms": ["youtube"],
  "platform_content": {
    "youtube": {
      "content": "Our autumn menu is here. Which drink first?"
    }
  },
  "scheduled_at": "2026-10-16T09:30:00Z"
}
```

Other platforms: [LinkedIn](https://postprism.app/docs/platforms/linkedin), [X (Twitter)](https://postprism.app/docs/platforms/twitter), [TikTok](https://postprism.app/docs/platforms/tiktok), [Pinterest](https://postprism.app/docs/platforms/pinterest), [Bluesky](https://postprism.app/docs/platforms/bluesky). Writing limits for every network are in our [character limit](https://postprism.app/glossary/character-limit) reference, and the [YouTube scheduler](https://postprism.app/platforms/youtube-scheduler) page covers scheduling from the app.