# Generations

Generations are AI-created, ready-to-post content suggestions. Viraloop uses the workspace's brand context (identity, tone of voice, content angles) and its Turbo configuration to produce a batch of suggestions you can review and then publish as posts.

## What a suggestion is

Each suggestion contains:

- `id`: use it later as `suggestionId` when publishing
- `format`: one of `walloftext`, `slideshow`, `greenscreen`
- `caption`: the on-screen text of the video itself (the hook the viewer reads)
- `postCaption`: the post body, the description text published alongside the video on the platform
- `hashtags`: hashtags to publish with the post
- `why`: a short rationale for why this suggestion should perform
- `angle`: the content angle it was derived from
- `deck`: the editable render blueprint (text boxes, ratio, media) used to render the video server-side
- `status`: `pending` (awaiting review), `accepted` or `scheduled`

`caption` and `postCaption` are separate on purpose: the first is part of the video, the second is platform metadata. Both can be overridden when you create the post.

## Formats

- `walloftext`: a bold text overlay carried by a simple background video
- `slideshow`: a swipeable sequence of image slides with text
- `greenscreen`: a green-screen style meme format

Pass `format` to force one of them, or omit it to use the workspace's configured content mix.

## Generating

`POST /generations` is synchronous: the request returns when generation finishes, typically 5 to 60 seconds depending on `count` (1 to 10). Content generation costs no credits in v1. The endpoint is rate limited to 10 requests per 300 seconds and supports the `Idempotency-Key` header for safe retries.

```bash
curl -s -X POST https://viraloop.io/api/v1/generations \
  -H "Authorization: Bearer $VIRALOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 3, "format": "walloftext"}'
```

```bash
viraloop generate --count 3 --json
```

Optional body fields: `influencerId` features that AI influencer in every suggestion, `workspaceId` targets a workspace other than the team's default. Requires the `generations:write` scope.

## Reviewing

List the queue (automation-owned suggestions are excluded) and inspect single suggestions:

```bash
viraloop generations list --json
viraloop generations get <id> --json
```

`GET /generations` supports `status`, `page`, `limit` and `workspaceId` filters. `GET /generations/{id}` returns the full deck, rationale and remix source. Both require the `generations:read` scope.

## Previewing before accepting

`GET /generations/{id}` returns the full `deck`: slide image URLs, caption
text boxes (text, position, styling) and the background clip or meme assets
for the video formats. Render those client-side (image or clip with the
caption text overlaid) as the preview your users accept or skip from.
Previewing and accepting cost nothing; billing only happens when a piece's
media is downloaded or published.

## Getting the media files (serve them yourself)

To fetch a suggestion's finished media instead of (or before) publishing:

1. Accept it: `POST /generations/{id}/accept` returns a `contentId`.
2. Download: `GET /content/{contentId}/download`. The first call starts the
   server-side render and returns `409`; poll until it returns `200` with the
   files (typically under a minute).

```bash
viraloop generations accept <id> --json
viraloop content download <contentId> --json
```

## Publishing

Publish a suggestion by passing its id to `POST /posts`:

```bash
viraloop posts create --suggestion <id> --accounts tiktok:<accountId> --when asap --wait --json
```

If the suggestion is already scheduled, this returns `409` with error type `conflict`; generate or pick another. See [posts and scheduling](/developers/docs/posts-and-scheduling) for accounts, timing and polling.