ANanam
Personas

create persona

Changed on

Create a new persona

post/v1/personas

Request

  • Base URL
    https://api.anam.ai
  • URL
    https://api.anam.ai/v1/personas
  • Auth
    HTTP bearer

Request body

namestring

Name of the persona

descriptionstring

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

avatarIdstring

The avatar to use.

avatarModel'cara-3' | 'cara-4' | 'cara-4.1-express' | 'cara-4-latest'

Avatar model version. cara-4 is pinned to a stable checkpoint; cara-4.1-express is the Cara-4.1 Express model; cara-4-latest tracks the newest Cara 4 checkpoint and may change between sessions.

voiceIdstring

The voice to use.

llmIdstring

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

systemPromptstring

System prompt for the LLM.

skipGreetingboolean

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

uninterruptibleGreetingboolean

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

initialMessagestring nullable

Custom first message the persona speaks to open the conversation. If empty or not provided, the persona generates its own greeting.

zeroDataRetentionboolean

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

maxSessionLengthSecondsinteger nullable

Maximum length in seconds of every session with this persona. It can only shorten the plan's session limit, never extend it. Omit or send null for no persona limit.

languageCodestring

Supported ISO 639 language code override (including "yue" for Cantonese) for transcription, replaces organisation level settings and multilingual (default) mode.

toolIdsstring[]

Array of tool IDs to attach to the persona.

Example request

{
  "name": "Cara",
  "avatarId": "071b0286-4cce-4808-bee2-e642f1062de3",
  "avatarModel": "cara-4",
  "voiceId": "de23e340-1416-4dd8-977d-065a7ca11697",
  "llmId": "a7cf662c-2ace-4de1-a21e-ef0fbf144bb7",
  "systemPrompt": "You are a helpful assistant",
  "initialMessage": "Hi there! I'm excited to chat with you today.",
  "maxSessionLengthSeconds": 600,
  "voiceDetectionOptions": {
    "endOfSpeechSensitivity": 0.5,
    "silenceBeforeSkipTurnSeconds": 5,
    "silenceBeforeSessionEndSeconds": 60,
    "silenceBeforeAutoEndTurnSeconds": 5,
    "speechEnhancementLevel": 0.8,
    "sttProvider": "anam"
  },
  "languageCode": "en",
  "voiceGenerationOptions": {
    "stability": 0.5,
    "speed": 1
  },
  "toolIds": [
    "tool-id-1",
    "tool-id-2"
  ]
}

Response

Successfully created persona

idstring uuid

Unique identifier for the persona.

namestring

Human-readable name of the persona.

descriptionstring nullable

Free-form description of the persona.

personaPresetstring

Deprecated. Name of the legacy preset an older persona was created from, if any. Presets can no longer be set; use avatarId and voiceId.

avatarModelstring nullable

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

voiceSpeednumber nullable

Speech rate multiplier applied to the voice.

llmIdstring uuid nullable

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

toolsobject[]

Tool configurations currently attached to the persona.

knowledgeobject[]

Knowledge group attachments currently active on the persona.

enableAudioPassthroughboolean

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

skipGreetingboolean

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

zeroDataRetentionboolean

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

maxSessionLengthSecondsinteger nullable

Maximum length in seconds of every session with this persona, or null when only the plan's session limit applies.

widgetConfigobject

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

createdAtstring date-time

Timestamp when the persona was created.

updatedAtstring date-time

Timestamp when the persona was last updated.

Example response

{
  "voiceDetectionOptions": {
    "endOfSpeechSensitivity": 0.5,
    "silenceBeforeSkipTurnSeconds": 5,
    "silenceBeforeSessionEndSeconds": 60,
    "silenceBeforeAutoEndTurnSeconds": 5,
    "speechEnhancementLevel": 0.8,
    "sttProvider": "anam"
  },
  "voiceGenerationOptions": {
    "stability": 0.5,
    "speed": 1
  }
}

Changes

  • 29e4b719d620Revision changes
    • warning

      the request property's maxLength was set to 191

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • e85ef0cd491eRevision changes
    • info

      added the non-success response with the status