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:

Accept it: POST /generations/{id}/accept returns a contentId.
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 for accounts, timing and polling.

Generations

What a suggestion is

Formats

Generating

Reviewing

Previewing before accepting

Getting the media files (serve them yourself)

Publishing

Want the short version?