# Post types

The six formats, all created by the same endpoint, with a call for each.

Posttar has six content formats, and one endpoint creates all of them: `POST /posts`, with a `format` parameter. Leave `format` out and you get `carousel`, the plain carousel.

| `format` | What it is | Media |
| --- | --- | --- |
| `carousel` | Carousel: image slides with a caption | Image carousel |
| `caption_reel` | Read-the-caption reel: three text blocks over a clip | Short video |
| `animated_audio` | Animated audio reel: the project voice narrates, over a waveform | Short video |
| `narrated_photos` | Narrated photos reel: the project voice narrates, one AI photo per passage | Short video |
| `premium_carousel` | Premium carousel: six pages drawn whole by the model | Image carousel |
| `infographic` | Infographic: one vertical piece drawn whole by the model | Short video, silent |

> The four preview formats (`animated_audio`, `narrated_photos`, `premium_carousel`, `infographic`) are enabled per workspace. Calling one the workspace does not have answers `403` with `forbidden`, and nothing is charged. `carousel` and `caption_reel` are open to everyone.

## One call per format

Every one of them costs 1 credit, answers `202`, and finishes in the background. Poll `GET /posts/:id` until `status` leaves `queued` and `generating`.

Carousel. The default, so `format` is optional here.

```bash
curl -X POST -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
  -d '{"projectId":"c85848ba-...","theme":"three signs your niche is too broad"}' \
  "https://api.posttar.com/v1/posts"
```

Read-the-caption reel. The background clip is chosen by Posttar, and the response says which source it used.

```bash
curl -X POST -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
  -d '{"projectId":"c85848ba-...","theme":"why your niche is too broad",
       "format":"caption_reel"}' \
  "https://api.posttar.com/v1/posts"
```

Animated audio reel. Needs a voice on the project; without one the call is refused with `invalid_state` and the message says where to record it.

```bash
curl -X POST -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
  -d '{"projectId":"c85848ba-...","theme":"how i price my work","format":"animated_audio"}' \
  "https://api.posttar.com/v1/posts"
```

Narrated photos reel. Same voice requirement, one AI photo per passage instead of the waveform.

```bash
curl -X POST -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
  -d '{"projectId":"c85848ba-...","theme":"my first client","format":"narrated_photos"}' \
  "https://api.posttar.com/v1/posts"
```

Premium carousel. Six pages drawn whole, instead of text over a template.

```bash
curl -X POST -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
  -d '{"projectId":"c85848ba-...","theme":"the 5 stages of a launch",
       "format":"premium_carousel"}' \
  "https://api.posttar.com/v1/posts"
```

Infographic. One vertical piece, published as a silent reel so it keeps video distribution.

```bash
curl -X POST -H "Authorization: Bearer $POSTTAR_KEY" -H "Content-Type: application/json" \
  -d '{"projectId":"c85848ba-...","theme":"freelance rates by years of experience",
       "format":"infographic"}' \
  "https://api.posttar.com/v1/posts"
```

The answer has the same shape for all six. `format` echoes what was created, and `clipSource` appears only for `caption_reel`, which is the only format with a background clip.

```json
{
  "postId": "dd8d142c-...",
  "format": "caption_reel",
  "state": "generating",
  "clipSource": "library",
  "remainingCredits": 5
}
```

## The two limits worth knowing before you call

- `theme` is capped at 10,000 characters, except on `animated_audio` and `narrated_photos`, where it stops at 500: there the theme becomes a spoken script.
- `link` (a page for Posttar to read before writing) works only on `carousel`. With any other format the call is refused instead of ignoring it, because ignoring it would spend a credit on a post about the wrong subject.

## What is editable after it is created

Every format is readable, schedulable, publishable and deletable through the API. Format-specific editing is uneven: the carousel has slide endpoints, the read-the-caption reel has `PATCH /reels/:id` plus clip and track endpoints, and the animated audio reel has `PATCH /audiograms/:id`. The other three have no editing endpoints yet, so a post of those formats is create-then-publish through the API, or editable in the app.