Skip to main content
POST
/
v1
/
personas
create persona
curl --request POST \
  --url https://api.anam.ai/v1/personas \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Cara",
  "description": "A helpful assistant",
  "avatarId": "071b0286-4cce-4808-bee2-e642f1062de3",
  "voiceId": "de23e340-1416-4dd8-977d-065a7ca11697",
  "llmId": "a7cf662c-2ace-4de1-a21e-ef0fbf144bb7",
  "systemPrompt": "You are a helpful assistant."
}
'
{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Cara",
  "description": "A helpful assistant",
  "personaPreset": "",
  "avatar": {
    "id": "071b0286-4cce-4808-bee2-e642f1062de3",
    "displayName": "Liv",
    "variantName": "home",
    "imageUrl": "https://lab.anam.ai/persona_thumbnails/liv_home.png",
    "videoUrl": "https://anam-prod.r2.cloudflarestorage.com/avatars/v2/stock/liv_home/idling_video.mp4?X-Amz-Signature=...",
    "createdAt": "2026-04-20T10:00:00.000Z",
    "updatedAt": "2026-04-20T10:00:00.000Z",
    "createdByOrganizationId": null,
    "availableVersions": [
      "v1",
      "v2",
      "cara-4-3"
    ],
    "activeVersion": "v2"
  },
  "avatarModel": "cara-3",
  "voice": {
    "id": "de23e340-1416-4dd8-977d-065a7ca11697",
    "displayName": "Lucy - Fresh & Casual",
    "provider": "ELEVENLABS",
    "providerVoiceId": "lcMyyd2HUfFzxdCaC4Ta",
    "providerModelId": "eleven_flash_v2_5",
    "sampleUrl": "https://newgxnc1uqs0jnqm.public.blob.vercel-storage.com/voice-samples/de23e340-1416-4dd8-977d-065a7ca11697/1760617899390.mp3",
    "previewSampleUrl": "https://newgxnc1uqs0jnqm.public.blob.vercel-storage.com/voice-samples/de23e340-1416-4dd8-977d-065a7ca11697/1760617899390.mp3",
    "gender": "FEMALE",
    "country": "GB",
    "description": "Energetic and youthful British voice, perfect for narrations and conversational agents.",
    "displayTags": [
      "fast"
    ],
    "isZdr": true,
    "createdByOrganizationId": null,
    "createdAt": "2026-04-20T10:00:00.000Z",
    "updatedAt": "2026-04-20T10:00:00.000Z"
  },
  "voiceSpeed": 1,
  "llmId": "a7cf662c-2ace-4de1-a21e-ef0fbf144bb7",
  "brain": {
    "personality": null,
    "systemPrompt": "You are a helpful assistant."
  },
  "tools": [],
  "knowledge": [],
  "shareLinks": null,
  "primaryShareLink": null,
  "enableAudioPassthrough": false,
  "skipGreeting": false,
  "zeroDataRetention": false,
  "voiceDetectionOptions": null,
  "voiceGenerationOptions": null,
  "widgetConfig": {},
  "createdAt": "2026-04-20T10:00:00.000Z",
  "updatedAt": "2026-04-20T10:00:00.000Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Configuration for the new persona. avatarId, voiceId, and llmId are references to existing resources in your organization. systemPrompt, if provided, is merged into the brain field server-side. Setting zeroDataRetention to true requires both the voice and LLM to be ZDR-compatible and an enterprise plan.

​
name
string

Name of the persona

Example:

"Cara"

​
description
string

Description of the persona, for example "A helpful assistant". Does not affect the persona's behavior.

​
avatarId
string

The avatar to use.

Example:

"071b0286-4cce-4808-bee2-e642f1062de3"

​
avatarModel
enum<string>

Avatar model version. Models with the '-latest' suffix are invite only.

Available options:
cara-2,
cara-3,
cara-4-latest
Example:

"cara-3"

​
voiceId
string

The voice to use.

Example:

"de23e340-1416-4dd8-977d-065a7ca11697"

​
llmId
string

The LLM to use. To disable the LLM, use 'CUSTOMER_CLIENT_V1'.

Example:

"a7cf662c-2ace-4de1-a21e-ef0fbf144bb7"

​
systemPrompt
string

System prompt for the LLM

Example:

"You are a helpful assistant"

​
skipGreeting
boolean

Whether to skip the greeting message when starting a session with this persona.

Example:

false

​
uninterruptibleGreeting
boolean

When true, the greeting message cannot be interrupted by the user.

Example:

false

​
zeroDataRetention
boolean

When true, session data is not stored after the conversation ends

Example:

false

​
voiceDetectionOptions
object

Options for voice activity detection during user speech input.

​
languageCode
string

ISO 639-1 formatted language code override for transcription, replaces organisation level settings and multilingual (default) mode.

Example:

"en"

​
voiceGenerationOptions
ElevenLabs V1 · object

Configuration options for voice generation.

​
toolIds
string[]

Array of tool IDs to attach to the persona.

Example:
["tool-id-1", "tool-id-2"]

Response

Successfully created persona

Full persona shape returned by the create, get, and update endpoints.

​
id
string<uuid>

Unique identifier for the persona.

​
name
string

Human-readable name of the persona.

​
description
string | null

Free-form description of the persona.

​
personaPreset
string

Name of the preset the persona was cloned from, if any.

​
avatar
object

Avatar currently attached to the persona.

​
avatarModel
string | null

Public model version (e.g. cara-3) used when rendering the avatar.

​
voice
object

Voice currently attached to the persona.

​
voiceSpeed
number | null

Speech rate multiplier applied to the voice.

​
llmId
string<uuid> | null

ID of the LLM the persona uses, or null for presets that don't run an LLM.

​
brain
object

Persona behaviour configuration applied on top of the raw LLM.

​
tools
object[]

Tool configurations currently attached to the persona.

​
knowledge
object[]

Knowledge group attachments currently active on the persona.

​
shareLinks
object[] | null

All share links ever issued for this persona.

​
primaryShareLink
object

The primary share link attached to the persona, if one has been created.

​
enableAudioPassthrough
boolean

Whether audio is passed through from the client instead of being generated server-side.

​
skipGreeting
boolean

Whether the persona skips the greeting message at the start of a session.

​
zeroDataRetention
boolean

Whether session data is discarded instead of stored after the conversation ends.

​
voiceDetectionOptions
object

Voice activity detection tuning for user speech.

​
voiceGenerationOptions
ElevenLabs V1 · object

Provider-specific voice generation tuning.

​
widgetConfig
object

Widget rendering overrides (e.g. removing the watermark).

​
createdAt
string<date-time>

Timestamp when the persona was created.

​
updatedAt
string<date-time>

Timestamp when the persona was last updated.

Last modified on April 22, 2026