Working with personas

A persona bundles the choices that make one video sound like another: the voice, the text model, and what the character is supposed to know about.

Every content item needs one. persona_id is required on POST /contents.

Scopes: read to list, write to create and edit, delete to remove.

What's in one

Field	Meaning
name	Your label for it
text_ai	Credential id for the model that writes the script
audio_ai	Credential id for the voice
specialty	What this persona talks about, in its own words
custom_settings	Free-form extra settings

Listing

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

{
  "page": 1,
  "total_pages": 1,
  "total_items": 1,
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Science explainer",
      "text_ai": "Gemini 3.1 Flash",
      "audio_ai": "Aoede",
      "has_pace": true,
      "text_is_internal": true,
      "audio_model_class": "self_hosted",
      "audio_model_name": "Aoede",
      "created_on": "2026-08-02T09:12:00+00:00"
    }
  ]
}

The last four fields are the cost-relevant ones:

• text_is_internal — script generation is billed at the internal multiplier
• audio_model_class — self_hosted is cheaper than external
• audio_model_name — the actual voice, so you can name it in a picker
• has_pace — whether this voice supports a pace setting

Together they let you predict what a video with this persona will cost before you generate it.

Pagination differs here

GET /personas takes offset with a default of 10 and a cap of 100. The other list endpoints accept only 12 or 24, silently falling back to 12. It is an inconsistency in the API, not in these docs.

text_ai or audio_ai reading "N/A" means the underlying credential has gone missing — the persona will not generate until it is fixed.

Creating

curl -s -X POST https://api.botlobby.ai/v1/personas \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Science explainer",
    "text_ai": "c0ffee00-1111-2222-3333-444455556666",
    "audio_ai": "deadbeef-1111-2222-3333-444455556666",
    "specialty": "Astronomy and space missions, explained plainly"
  }'

name, text_ai, audio_ai and specialty are all required.

Three plan limits apply, and all three surface as 400 with an explanatory error:

• Which models you may use. Not every model is available on every plan.
• How long specialty may be. A per-plan character limit.
• How many personas you may hold. A per-plan count limit.

Editing

curl -s -X PUT https://api.botlobby.ai/v1/personas/PERSONA_ID \
  -H "Authorization: Bearer $BOTLOBBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"specialty": "Astronomy, space missions and exoplanet science"}'

Every field is optional — send only what changes. The same plan limits apply.

Editing a persona does not retroactively change content already generated with it. Existing videos keep the script and voice they were made with.

Deleting

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

Permanent

Unlike content, which is soft-deleted and merely disappears from your view, a persona is removed outright and cannot be recovered.

Requires the delete scope, which is not in a new key's defaults.

Writing a good specialty

specialty steers what the script actually says, so it does more work than the name suggests. Concrete beats broad:

• Vague: "science"
• Better: "Astronomy and space missions, explained plainly for people who never studied physics"

It describes the persona's remit and register, not a single video's topic — the topic comes from full_text on each content item.