Skip to main content

Quickstart

From nothing to a rendered video in seven requests. Every sample here runs as written once you set BOTLOBBY_API_KEY.

1. Create a key​

In the web app, go to Settings → API Keys and create one. Two things to know:

  • The key is shown exactly once. Only a SHA-256 hash is stored, so a lost key cannot be recovered — mint a new one and revoke the old.
  • API access is a top-tier plan feature. If the button sends you to pricing, that is why.

Leave the default scopes (read and generate) selected — they cover everything on this page.

export BOTLOBBY_API_KEY="bl_live_..."

2. Check the key works​

Cheapest possible request, and it needs no scope at all:

curl -s https://api.botlobby.ai/v1/api-keys/introspect \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"
{
  "active": true,
  "subject": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "scopes": ["read", "generate"]
}

A 401 here means the key is wrong — see Errors.

3. Check your balance​

Generation spends credits, so know what you have:

curl -s https://api.botlobby.ai/v1/users/credits \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"

Spend against total_credits.

4. Pick a persona​

A persona is the voice and models a video is generated with. Every content item needs one.

curl -s https://api.botlobby.ai/v1/personas \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"

Take an id from items. If the list is empty, create one in the web app or see Working with personas.

5. Create the content​

This generates the script, so it costs credits.

curl -s -X POST https://api.botlobby.ai/v1/contents \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "full_text": "The James Webb telescope found water vapour on K2-18b",
    "persona_id": "PERSONA_ID_FROM_STEP_4",
    "title": "Water on a distant world"
  }'
The id is nested

The response is {"message": ..., "item": {"id": ..., "title": ...}} — read item.id, not id.

{
  "message": "Content generated successfully",
  "item": { "id": "22222222-2222-4222-8222-222222222222", "title": "Water on a distant world" }
}

Keep item.id — call it CONTENT_ID. Everything below uses it.

6. Generate the voiceover​

curl -s -X POST https://api.botlobby.ai/v1/gen/tts \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"creation_id": "CONTENT_ID"}'

Asynchronous. Poll until the status reaches AUDIO_PROCESSED:

curl -s https://api.botlobby.ai/v1/gen/task-status/CONTENT_ID \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"

7. Render the video​

Pick a background first:

curl -s https://api.botlobby.ai/v1/gen/static-videos \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"
No id field

The response has name, not id. name is the video_id the renderer wants — "1" means static-videos/1.mp4.

You can also skip the list entirely and pass a visual-source sentinel: stock, web_search, generate or custom.

curl -s -X POST https://api.botlobby.ai/v1/gen/video \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creation_id": "CONTENT_ID",
    "video_id": "stock",
    "orientation": "vertical"
  }'

Poll task-status again until VIDEO_PROCESSED. Then fetch the content item to get a signed video_url:

curl -s https://api.botlobby.ai/v1/contents/CONTENT_ID \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY"

That URL is time-limited — fetch it fresh rather than storing it.

Where to go next​