Getting started

The Viraloop API generates ready-to-post short-form videos (wall of text, slideshow, green screen) from your brand's context and publishes them to connected TikTok, Instagram and YouTube accounts. This guide takes you from an empty terminal to a published post.

Base URL: https://viraloop.io/api/v1. Every response uses one envelope: { "success": true, "data": ..., "pagination"? } on success, { "success": false, "error": { "type", "message" } } on failure.

1. Create an API key

Create a key in the dashboard at https://viraloop.io/settings/developers. Pick the scopes the key needs; for this guide use accounts:read, generations:write, posts:read and posts:write. Keys look like vl_live_... and the full key is shown once at creation, so store it somewhere safe (an environment variable or secret manager).

export VIRALOOP_API_KEY=vl_live_...

2. Verify auth with /me

GET /me works with any valid key and returns your team, credit balance, plan, default workspace and the scopes granted to the key.

curl -s https://viraloop.io/api/v1/me \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"

Or with the CLI:

npm install -g viraloop
viraloop login        # or rely on the VIRALOOP_API_KEY env var
viraloop whoami --json

3. Find your connected accounts

Posting requires at least one connected social account. Connecting accounts (OAuth) happens in the web app at https://viraloop.io/accounts, not through the API. List what is connected and note the account ids:

curl -s https://viraloop.io/api/v1/accounts \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"

viraloop accounts list --json

4. Generate content

POST /generations is synchronous: the request returns when generation finishes, typically 5 to 60 seconds depending on count. It costs no credits in v1.

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

viraloop generate --count 2 --json

Each suggestion in the response has an id, a caption (the on-screen text), a postCaption (the post body), hashtags and a why rationale. See the generations guide for the details.

5. Publish a post

Publish a suggestion you like with POST /posts, targeting account ids from step 3:

curl -s -X POST https://viraloop.io/api/v1/posts \
  -H "Authorization: Bearer $VIRALOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"suggestionId": "<suggestionId>", "selectedAccounts": {"tiktok": ["<accountId>"]}, "schedule": "asap"}'

viraloop posts create --suggestion <suggestionId> \
  --accounts tiktok:<accountId> --when asap --wait --json

The API responds with 202 and a statusUrl; the video renders server-side after the call returns. The CLI's --wait flag polls for you.

6. Poll until it is posted

curl -s https://viraloop.io/api/v1/posts/<postId> \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"

viraloop posts get <postId> --json

Terminal statuses are posted, partial, completed and failed; a renderStatus of failed is also terminal. Once posted, the response includes a per-platform postUrl and an analytics snapshot (views, likes, comments, shares).

Next steps