> ## Documentation Index > Fetch the complete documentation index at: https://anam.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # create persona > Create a new persona ## OpenAPI ````yaml https://api.anam.ai/swagger.json post /v1/personas openapi: 3.1.0 info: title: Anam AI API version: '1.0' servers: - url: https://api.anam.ai description: Anam API security: - BearerAuth: [] tags: - name: Sessions - name: Avatar Videos - name: Meetings - name: Personas - name: Avatars - name: Voices - name: Pronunciation Dictionaries - name: LLMs - name: Knowledge - name: Tools - name: Share Links - name: Engine paths: /v1/personas: post: tags: - Personas summary: create persona description: Create a new persona operationId: createPersona requestBody: description: >- 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 the voice, LLM and `voiceDetectionOptions.sttProvider` to be ZDR-compatible and an enterprise plan. required: true content: application/json: examples: default: $ref: '#/components/examples/PersonaCreate' schema: type: object required: - name properties: name: type: string maxLength: 191 description: Name of the persona example: Cara description: type: string description: >- Description of the persona, for example "A helpful assistant". Does not affect the persona's behavior. avatarId: type: string description: The avatar to use. example: 071b0286-4cce-4808-bee2-e642f1062de3 avatarModel: type: string example: cara-4 description: >- Avatar model version. `cara-4` is pinned to a stable checkpoint; `cara-4-latest` tracks the newest Cara 4 checkpoint and may change between sessions. `cara-5-latest` is an early-access preview that tracks the newest Cara 5 checkpoint; it is available only to organizations that have been granted it, and other organizations get 403. enum: - cara-3 - cara-4 - cara-4.1-express - cara-4-latest - cara-5-latest voiceId: type: string description: The voice to use. example: de23e340-1416-4dd8-977d-065a7ca11697 llmId: type: string description: >- The LLM to use. To disable the LLM, use 'CUSTOMER_CLIENT_V1'. example: a7cf662c-2ace-4de1-a21e-ef0fbf144bb7 systemPrompt: type: string description: System prompt for the LLM. example: You are a helpful assistant skipGreeting: type: boolean description: Skip the greeting when a session starts. example: false uninterruptibleGreeting: type: boolean description: The user can't interrupt the greeting. example: false initialMessage: type: string nullable: true description: >- What the persona says first. Empty or left out, it greets in its own words. example: Hi there! I'm excited to chat with you today. zeroDataRetention: type: boolean description: >- When true, session data is not stored after the conversation ends example: false maxSessionLengthSeconds: type: - integer - 'null' minimum: 60 maximum: 7200 description: >- Longest session with this persona, in seconds; it can only shorten the plan's limit. Omit or send `null` for no persona limit. example: 600 voiceDetectionOptions: $ref: '#/components/schemas/VoiceDetectionOptions' languageCode: type: string description: >- Supported ISO 639 language code override (including "yue" for Cantonese) for transcription, replaces organisation level settings and multilingual (default) mode. example: en voiceGenerationOptions: description: Configuration options for voice generation. oneOf: - $ref: '#/components/schemas/ElevenLabsV1VoiceGenerationOptions' - $ref: '#/components/schemas/ElevenLabsV2VoiceGenerationOptions' - $ref: '#/components/schemas/ElevenLabsV3VoiceGenerationOptions' - $ref: '#/components/schemas/ElevenLabsV4VoiceGenerationOptions' - $ref: >- #/components/schemas/CartesiaSonic3VoiceGenerationOptions - $ref: '#/components/schemas/FishAudioVoiceGenerationOptions' toolIds: type: array items: type: string description: Array of tool IDs to attach to the persona. example: - tool-id-1 - tool-id-2 responses: '201': description: Successfully created persona content: application/json: schema: $ref: '#/components/schemas/Persona' examples: default: $ref: '#/components/examples/PersonaResponse' '400': description: >- Bad request - Invalid persona data, avatarModel not supported by avatar, or an `avatarId`, `voiceId`, `llmId` or `toolIds` entry that is missing, deleted or not available to your organization. `personaPreset` is no longer supported and is rejected. A field too long to store is rejected with `details` naming the field and, when known, its maximum length, or with an empty `path` if the field cannot be identified. content: application/json: schema: type: object properties: error: type: string code: type: string description: >- Machine-readable reason, when one applies (for example `PERSONA_PRESET_UNSUPPORTED`). details: type: array description: Each invalid field, when the request failed validation. items: type: object properties: path: type: string message: type: string code: type: string summary: type: string description: >- The `details` entries as one line, when the request failed validation. examples: fieldTooLong: summary: A field is too long to store value: error: Validation error details: - path: name message: Must be at most 191 characters code: custom summary: 'name: Must be at most 191 characters' presetUnsupported: summary: A persona preset was sent value: error: >- personaPreset is no longer supported. Set avatarId and voiceId instead. code: PERSONA_PRESET_UNSUPPORTED voiceNotFound: summary: The voice was deleted or never existed value: error: Voice not found '401': description: Unauthorized - Invalid or missing API key '403': description: Forbidden - API key lacks the required permission '500': description: Server error '503': description: >- The API key could not be checked because of a temporary server problem. The key may be valid; retry after `Retry-After` seconds. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableError' components: examples: PersonaCreate: summary: Create a persona with the default Cara configuration value: 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. PersonaResponse: summary: A single persona resource (full shape) value: 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://example.com/avatar-preview.mp4?X-Amz-Signature=... createdAt: '2026-04-20T10:00:00.000Z' updatedAt: '2026-04-20T10:00:00.000Z' createdByOrganizationId: null availableVersions: - cara-3 activeVersion: cara-3 description: >- A friendly professional in a modern office setting, warm expression, business casual attire. displayTags: - professional - friendly - office renderStyle: realistic 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' schemas: VoiceDetectionOptions: type: object description: Options for voice activity detection during user speech input. properties: endOfSpeechSensitivity: type: number description: End-of-speech sensitivity, from 0 (least) to 1 (most sensitive). example: 0.5 minimum: 0 maximum: 1 silenceBeforeSkipTurnSeconds: type: number description: Seconds of silence before the user’s turn is skipped. example: 5 minimum: 0 maximum: 900 silenceBeforeSessionEndSeconds: type: number description: Seconds of silence before the session ends. example: 60 minimum: 0 maximum: 7200 silenceBeforeAutoEndTurnSeconds: type: number description: Seconds of silence before the user’s turn ends. example: 5 minimum: 0.5 maximum: 10 speechEnhancementLevel: type: number description: Speech enhancement, from 0 (none) to 1 (most). example: 0.8 minimum: 0 maximum: 1 sttProvider: type: string enum: - anam - deepgram - cartesia_ink_2 - inworld_stt_1 description: >- Speech-to-text provider to use. Defaults to the platform default when unset. The deepgram provider supports only these languageCode values: en, es, fr, de, hi, ru, pt, ja, it, nl. The cartesia_ink_2 provider supports only these languageCode values: en. The inworld_stt_1 provider supports only these languageCode values: ar, yue, zh, cs, da, nl, en, tl, fi, fr, de, el, hi, hu, id, it, ja, ko, mk, ms, fa, pl, pt, ro, ru, es, sv, th, tr, vi. The inworld_stt_1 provider cannot be used when zeroDataRetention is true. The inworld_stt_1 provider processes audio only in us, so it cannot be used when sessionOptions.regionPolicy is "strict" with any other region. example: anam ElevenLabsV1VoiceGenerationOptions: title: ElevenLabs V1 type: object description: Voice generation options for ElevenLabs V1 models. properties: stability: type: number description: >- Controls how stable the generated voice is between each generation, between 0 (more varied/higher emotional range) and 1 (more stable/less emotional range). example: 0.5 minimum: 0 maximum: 1 similarityBoost: type: number description: >- Controls how close the generated voice is to the original speaker, between 0 (more varied) and 1 (more similar). example: 0 minimum: 0 maximum: 1 speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.7 (slower) and 1.2 (faster). example: 1 minimum: 0.7 maximum: 1.2 ElevenLabsV2VoiceGenerationOptions: title: ElevenLabs V2 type: object description: Voice generation options for ElevenLabs V2 models. properties: stability: type: number description: >- Controls how stable the generated voice is between each generation, between 0 (more varied/higher emotional range) and 1 (more stable/less emotional range). example: 0.5 minimum: 0 maximum: 1 similarityBoost: type: number description: >- Controls how close the generated voice is to the original speaker, between 0 (more varied) and 1 (more similar). example: 0.75 minimum: 0 maximum: 1 style: type: number description: >- Amplifies the style of the original speaker, between 0 and 1, it is recommended to keep this value low (0) to reduce latency. example: 0 minimum: 0 maximum: 1 useSpeakerBoost: type: boolean description: >- Whether to use speaker boost for the generated voice, enhancing the similarity to the original speaker. example: true speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.7 (slower) and 1.2 (faster). example: 1 minimum: 0.7 maximum: 1.2 model: $ref: '#/components/schemas/ElevenLabsModelOverride' ElevenLabsV3VoiceGenerationOptions: title: ElevenLabs V3 type: object additionalProperties: false description: >- Voice generation options for an eleven_v3 or eleven_v3_conversational voice, or for any voice whose model override is one of them. Only stability is supported. properties: stability: type: number description: >- Controls how stable the generated voice is, from 0 (more varied) to 1 (more stable). example: 0.5 minimum: 0 maximum: 1 model: $ref: '#/components/schemas/ElevenLabsModelOverride' ElevenLabsV4VoiceGenerationOptions: title: ElevenLabs V4 type: object additionalProperties: false description: >- Voice generation options for an eleven_v4 or eleven_v4_turbo voice, or for any voice whose model override is one of them. Only stability and similarityBoost are supported. properties: stability: type: number description: >- Controls how stable the generated voice is, from 0 (more varied) to 1 (more stable). example: 0.5 minimum: 0 maximum: 1 similarityBoost: type: number description: >- Controls how close the generated voice is to the original speaker, between 0 (more varied) and 1 (more similar). example: 0.75 minimum: 0 maximum: 1 model: $ref: '#/components/schemas/ElevenLabsModelOverride' CartesiaSonic3VoiceGenerationOptions: title: Cartesia Sonic-3 type: object description: Voice generation options for Cartesia Sonic-3 models. properties: volume: type: number description: >- Controls the volume level of the generated voice as a multiplier, between 0.5 (quieter) and 2.0 (louder). example: 1 minimum: 0.5 maximum: 2 speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.6 (slower) and 1.5 (faster). example: 1 minimum: 0.6 maximum: 1.5 emotion: type: string description: >- Sets the emotional tone of the generated voice. Supported emotions are: neutral, calm, angry, content, sad, scared. example: neutral oneOf: - type: string enum: - neutral - calm - angry - content - sad - scared FishAudioVoiceGenerationOptions: title: Fish Audio type: object description: Voice generation options for Fish Audio models. properties: volume: type: number description: >- Controls the volume level of the generated voice as a multiplier, between 0.5 (quieter) and 2.0 (louder). example: 1 minimum: 0.5 maximum: 2 speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.5 (slower) and 2.0 (faster). example: 1 minimum: 0.5 maximum: 2 Persona: type: object description: Full persona shape returned by the create, get, and update endpoints. properties: id: type: string format: uuid description: Unique identifier for the persona. name: type: string description: Human-readable name of the persona. description: type: - string - 'null' description: Free-form description of the persona. personaPreset: type: string deprecated: true description: >- Deprecated. Name of the legacy preset an older persona was created from, if any. Presets can no longer be set; use `avatarId` and `voiceId`. avatar: oneOf: - $ref: '#/components/schemas/Avatar' - type: 'null' description: Avatar currently attached to the persona. avatarModel: type: - string - 'null' description: >- Public model version (e.g. `cara-3`, `cara-4`) used when rendering the avatar. voice: oneOf: - $ref: '#/components/schemas/Voice' - type: 'null' description: Voice currently attached to the persona. voiceSpeed: type: - number - 'null' description: Speech rate multiplier applied to the voice. llmId: type: - string - 'null' format: uuid description: >- ID of the LLM the persona uses, or `null` for presets that don't run an LLM. brain: $ref: '#/components/schemas/PersonaBrain' tools: type: array items: type: object description: Tool configurations currently attached to the persona. knowledge: type: array items: type: object description: Knowledge group attachments currently active on the persona. shareLinks: type: - array - 'null' items: $ref: '#/components/schemas/ShareLink' description: All share links ever issued for this persona. primaryShareLink: type: - object - 'null' description: >- The primary share link attached to the persona, if one has been created. properties: token: type: string enabled: type: boolean enableAudioPassthrough: type: boolean description: >- Whether audio is passed through from the client instead of being generated server-side. skipGreeting: type: boolean description: >- Whether the persona skips the greeting message at the start of a session. zeroDataRetention: type: boolean description: >- Whether session data is discarded instead of stored after the conversation ends. maxSessionLengthSeconds: type: - integer - 'null' description: >- Maximum length in seconds of every session with this persona, or `null` when only the plan's session limit applies. voiceDetectionOptions: oneOf: - $ref: '#/components/schemas/VoiceDetectionOptions' - type: 'null' description: Voice activity detection tuning for user speech. voiceGenerationOptions: oneOf: - $ref: '#/components/schemas/ElevenLabsV1VoiceGenerationOptions' - $ref: '#/components/schemas/ElevenLabsV2VoiceGenerationOptions' - $ref: '#/components/schemas/ElevenLabsV3VoiceGenerationOptions' - $ref: '#/components/schemas/ElevenLabsV4VoiceGenerationOptions' - $ref: '#/components/schemas/CartesiaSonic3VoiceGenerationOptions' - $ref: '#/components/schemas/FishAudioVoiceGenerationOptions' - type: 'null' description: Provider-specific voice generation tuning. widgetConfig: type: object description: Widget rendering overrides (e.g. removing the watermark). createdAt: type: string format: date-time description: Timestamp when the persona was created. updatedAt: type: string format: date-time description: Timestamp when the persona was last updated. ServiceUnavailableError: type: object required: - error - message properties: error: type: string example: Service temporarily unavailable message: type: string example: We could not check your API key. Please retry shortly. ElevenLabsModelOverride: type: string enum: - eleven_v4_turbo - eleven_v3_conversational - eleven_v4 - eleven_v3 - eleven_flash_v2_5 - eleven_multilingual_v2 - eleven_flash_v2 - eleven_turbo_v2_5 description: >- Replaces the voice's ElevenLabs model for generation. Must be an ElevenLabs model supported for voice imports. The other options must be valid for this model: for example, eleven_v4 accepts only stability and similarityBoost. Avatar: type: object description: A face preset that a persona can use as its visual representation. properties: id: type: string format: uuid description: Unique identifier for the avatar. displayName: type: string description: Human-readable name shown in the Lab and share links. variantName: type: string description: >- Name of the specific variant (e.g. lighting or pose) within the avatar family. imageUrl: type: string format: uri description: >- Still image of the avatar, framed exactly like `videoUrl`, `idleVideoUrl` and a landscape session (the default). Use it as the thumbnail, poster or loading image wherever a preview video or the live stream replaces it, and give the image and the video the same box, `object-fit` and `object-position` so the avatar doesn't move when they swap. For Cara 4 avatars this is the 1152x768 landscape crop (the same image as `landscapeImageUrl`). Cara 4 avatars used to return their square source image here; that image is now `sourceImageUrl`. Empty when the avatar has no image yet, or when its images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. sourceImageUrl: type: string format: uri description: >- The image the avatar was created from. For Cara 4 avatars it is square (1152x1152) and shows more of the scene than the 1152x768 crop that preview videos and sessions use, so the avatar appears to zoom in when a video or call replaces it. Don't use it as a thumbnail, poster or loading image next to `videoUrl` or a session; use `imageUrl`, `landscapeImageUrl` or `portraitImageUrl`. For legacy avatars it is the same landscape image as `imageUrl`. Empty when the avatar's images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. landscapeImageUrl: type: - string - 'null' format: uri description: >- Still image cropped exactly as the engine frames landscape (1152x768) output, which is also the framing of `videoUrl` and `idleVideoUrl`. Use it with landscape sessions (the default) and preview videos. For avatars with legacy landscape source images this is the source image. `null` when the avatar's images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. portraitImageUrl: type: - string - 'null' format: uri description: >- Still image cropped exactly as the engine frames portrait (768x1152) output. Use it as the poster for a session started with portrait `videoWidth`/`videoHeight`. Preview videos are landscape, so don't swap this image for `videoUrl`. `null` when the avatar cannot render portrait output or its images are not available through the API. May be a time-limited link; see `imageUrlsExpireAt`. imageUrlsExpireAt: type: - string - 'null' format: date-time description: >- When set, `imageUrl`, `sourceImageUrl`, `landscapeImageUrl` and `portraitImageUrl` are time-limited links that stop working at this time; fetch the avatar again for fresh ones. They stay valid for at least an hour, and repeated requests within the same hour return the same links, so browsers can cache them. Treat them as credentials for those images, since anyone holding a link can load the image until it expires. `null` when the image URLs don't expire. videoUrl: type: - string - 'null' format: uri description: >- Signed URL for a verified muted MP4 preview of the avatar. Uses the idle loop if the talking preview is unavailable. Landscape (1152x768 for Cara 4 avatars, 720x480 for legacy avatars) and framed exactly like `imageUrl`, so pair it with `imageUrl` or `landscapeImageUrl`, not `sourceImageUrl`. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when the preview is unavailable or still generating. idleVideoUrl: type: - string - 'null' format: uri description: >- Signed URL for a muted idling-loop MP4 of the avatar, if one exists. Landscape and framed exactly like `imageUrl`, like `videoUrl`. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. `null` when unavailable or still generating. createdAt: type: string format: date-time description: Timestamp when the avatar was created. updatedAt: type: string format: date-time description: Timestamp when the avatar was last updated. createdByOrganizationId: type: - string - 'null' description: >- ID of the organization that created the avatar, or `null` for stock avatars. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created. availableVersions: type: array items: type: string description: >- Avatar models this avatar can be used with. Pass one of these values as `avatarModel` when creating a persona or starting a session. activeVersion: type: - string - 'null' description: >- Avatar model used by default when no explicit `avatarModel` is requested. description: type: - string - 'null' description: >- AI-generated description of the avatar's appearance, setting, and style. `null` if metadata generation has not completed. displayTags: type: array items: type: string description: >- Curated tags describing the avatar. Empty array if metadata generation has not completed. renderStyle: type: string enum: - realistic - animated_3d - illustrated - unknown description: >- Render style of the avatar. `unknown` covers custom avatars and avatars whose metadata has not yet been generated. Voice: type: object description: A voice preset a persona can use for text-to-speech. properties: id: type: string format: uuid description: Unique identifier for the voice. displayName: type: string description: Human-readable name shown in the Lab. provider: type: string enum: - CARTESIA - ELEVENLABS - FISH_AUDIO description: Upstream TTS provider for this voice. providerVoiceId: type: - string - 'null' description: The upstream provider's identifier for the voice. providerModelId: type: - string - 'null' description: The upstream provider's model identifier used to generate speech. sampleUrl: type: - string - 'null' format: uri description: URL of a short audio preview of the voice. previewSampleUrl: type: - string - 'null' format: uri description: Alias for `sampleUrl`, kept for backwards compatibility. gender: type: - string - 'null' enum: - MALE - FEMALE - NEUTRAL - null description: Perceived gender of the voice, if categorised. country: type: - string - 'null' description: ISO 3166-1 alpha-2 country code representing the voice's accent. description: type: - string - 'null' description: Free-form description of the voice's character. displayTags: type: array items: type: string description: Tags used to categorise the voice in the Lab UI. isZdr: type: boolean description: Whether this voice meets the Zero Data Retention requirements. createdByOrganizationId: type: - string - 'null' description: >- ID of the organization that created the voice, or `null` for stock voices. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created. createdAt: type: string format: date-time description: Timestamp when the voice was created. updatedAt: type: string format: date-time description: Timestamp when the voice was last updated. PersonaBrain: type: object description: Persona behaviour configuration applied on top of the raw LLM. properties: personality: type: - string - 'null' description: >- Free-form description of the persona's personality, used to seed the system prompt. systemPrompt: type: - string - 'null' description: System prompt sent to the LLM at the start of each session. ShareLink: type: object description: >- A shareable link to a persona. Can be used as a direct URL or embedded via the widget. properties: id: type: string format: uuid description: Unique identifier for the share link. token: type: string description: Opaque token appended to the public URL. type: type: string enum: - LINK - PLAYER_EMBED - ORB_EMBED description: Kind of share link — a direct URL, a player embed, or an orb embed. expiresAt: type: - string - 'null' format: date-time description: >- Timestamp after which the link no longer works, or `null` if the link does not expire. usageLimit: type: - integer - 'null' description: >- Maximum number of times the link can be used, or `null` for unlimited. usageCount: type: integer description: Number of times the link has been used. allowedOrigins: type: array items: type: string description: >- Origins permitted to load the link when embedded. Ignored when `allowAllOrigins` is true. allowAllOrigins: type: boolean description: Whether the link can be embedded on any origin. removeWatermark: type: boolean description: >- Whether the persona renders without the Anam watermark. Requires a plan that permits watermark removal. enabled: type: boolean description: Whether the link currently accepts connections. isPrimary: type: boolean description: >- Whether this is the persona's primary share link (at most one per persona). createdAt: type: string format: date-time description: Timestamp when the share link was created. securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.