---
title: "Get Voice Agent"
method: GET
path: "/v1/voice_agents/{agent_id}"
tags: ["Voice Agents"]
---

# Get Voice Agent

`GET /v1/voice_agents/{agent_id}`

## Request

- Base URL: `https://api.liveavatar.com`
- URL: `https://api.liveavatar.com/v1/voice_agents/{agent_id}`
- Auth: API key in header `X-API-KEY`

Retrieve a voice agent, including its full `agent_configuration`.

## Path parameters

- `agent_id` string, required

## Response `200`

Successful Response

- ResponseVoiceAgentResponseSchema
  - `code` integer
  - `data` VoiceAgentResponseSchema: A voice agent, including its full `agent_configuration`.
    - `id` string, required
    - `name` string, required
    - `agent_type` 'liveavatar_agent' | 'elevenlabs_agent' | 'cartesia_agent' | 'openai_agent', required: How a voice agent's conversation is run. * `liveavatar_agent` — the managed speech-to-text => LLM => text-to-speech pipeline. * `elevenlabs_agent` — an agent you host on ElevenLabs, referenced by id. * `cartesia_agent` — an agent you host on Cartesia, referenced by id. * `openai_agent` — OpenAI Realtime or GPT-Live (picked by `model`) on your own OpenAI key.
    - `is_public` boolean, required
    - `agent_configuration` union, required
      - FullAgentConfigSchema: `agent_configuration` for a `liveavatar_agent`. The conversation runs on the managed speech-to-text => LLM => text-to-speech pipeline, using the voice, context, and language selected here. Unknown fields are rejected rather than silently ignored, and the language must be supported by the chosen speech-to-text provider and text-to-speech model.
        - `agent_type` 'liveavatar_agent'
        - `mode` 'FULL' | 'LITE'
        - `voice_id` string, uuid, required: Voice used by the pipeline TTS stage
        - `context_id` string, uuid: Context ID
        - `language` string: Language
        - `voice_settings` union: Additional voice settings (provider-specific, discriminated by 'provider' field)
          - ElevenLabsVoiceSettings: ElevenLabs-specific voice settings for TTS configuration.
            - `provider` 'elevenLabs'
            - `speed` number
            - `stability` number
            - `similarity_boost` number
            - `style` number
            - `use_speaker_boost` boolean
            - `model` 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_v3' | 'eleven_v3_conversational' | 'eleven_v4_turbo'
            - `apply_language_text_normalization` boolean: Apply ElevenLabs language-specific text normalization. Improves pronunciation for languages with complex orthography — currently only Japanese ('ja') is supported. Enabling this adds latency, so it is opt-in and only valid when the session language is set to 'ja'.
          - FishAudioVoiceSettings: Fish Audio-specific voice settings for TTS configuration.
            - `provider` 'fish'
            - `speed` number
            - `model` 's1' | 's2' | 's2-pro' | 's2.1-pro'
            - `latency_mode` 'normal' | 'balanced' | 'low': Latency mode: 'normal' (best quality), 'balanced', or 'low' (lowest latency).
          - CartesiaVoiceSettings: Cartesia-specific voice settings for TTS configuration.
            - `provider` 'cartesia'
            - `speed` number
            - `model` 'sonic-3.6' | 'sonic-3.5' | 'sonic-3' | 'sonic-2' | 'sonic-turbo'
        - `stt_config` STTConfigSchemaOutput: User-provided STT configuration.
          - `provider` 'deepgram' | 'assembly_ai' | 'gladia' | 'elevenlabs', required
        - `llm_settings` OpenAILLMSetting
          - `provider` 'openai'
          - `model` 'gpt-4o' | 'gpt-4o-mini' | 'gpt-5-nano' | 'gpt-5.4-nano': Recommended OpenAI chat models selectable for the FULL pipeline.
      - ElevenLabsAgentConfigSchemaOutput: `agent_configuration` for an `elevenlabs_agent`. The conversation is handled by an agent you host on ElevenLabs, referenced by its `agent_id` plus one of your stored secrets holding an ElevenLabs API key. The key is held by reference only and is never returned. Unknown fields are rejected rather than silently ignored, including fields that belong to a `liveavatar_agent` configuration.
        - `agent_type` 'elevenlabs_agent'
        - `mode` 'FULL' | 'LITE'
        - `agent_id` string, required: ElevenLabs Agent ID
        - `secret_id` string, uuid, required: Secret ID referencing an ELEVENLABS_API_KEY secret
      - CartesiaAgentConfigSchemaOutput: `agent_configuration` shape for the `cartesia` agent type. References a Cartesia-hosted agent by id plus a stored secret; the secret is held by reference only (`secret_id` → `space_secrets`), never inline. Mirrors `ElevenLabsAgentConfigSchema` exactly — field names align with the LITE-session `CartesiaAgentConfigSchema` (`src/sessions/session_token_schema.py`) so the session-start path can map one onto the other without renaming. `extra="forbid"` rejects unknown keys (and any liveavatar_agent fields sent against the wrong type) at write time.
        - `agent_type` 'cartesia_agent'
        - `mode` 'FULL' | 'LITE'
        - `agent_id` string, required: Cartesia Agent ID
        - `secret_id` string, uuid, required: Secret ID referencing a CARTESIA_API_KEY secret
      - OpenAIAgentConfigSchema: `agent_configuration` for an `openai_agent`. The conversation runs on OpenAI with your own OpenAI API key: the Realtime API, or full-duplex GPT-Live for a `gpt-live-*` model. The prompt comes from `context_id`. Fields, defaults and model/voice validation are the LITE-session `OpenAIRealtimeConfigSchema`'s, inherited, so session start maps one onto the other without renaming. Unknown fields are rejected rather than silently ignored.
        - `model` 'gpt-realtime' | 'gpt-realtime-mini' | 'gpt-realtime-2.1' | 'gpt-realtime-2.1-mini' | 'gpt-live-1': OpenAI speech-to-speech models. GPT-Live models run the full-duplex GPT-Live connector; the rest run the Realtime API. The two families differ in voices and GPT-Live has no temperature — ask the member (`is_gpt_live` / `voices` / `default_voice`) rather than matching on the slug.
        - `voice` union: Voice from the model's voice set. Defaults to 'alloy' (Realtime) or 'marin' (GPT-Live).
          - 'alloy' | 'ash' | 'ballad' | 'coral' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer' | 'sage' | 'verse' | 'marin' | 'cedar'
          - 'aster' | 'beacon' | 'cinder' | 'marin' | 'stone' | 'vesper'
        - `temperature` number: Sampling temperature. Realtime models only.
        - `secret_id` string, uuid, required: Secret ID referencing OPENAI_API_KEY secret
        - `context_id` string, uuid: Context ID.
        - `agent_type` 'openai_agent'
        - `mode` 'FULL' | 'LITE'
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `message` string

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-03** `8bc38e64ff31`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/liveavatar/apis/live-avatar-api/changes/v1/voice_agents/:agent_id/get.md)

---

[API](https://skmtc.dev/liveavatar/apis/live-avatar-api.md) - [All operations](https://skmtc.dev/liveavatar/apis/live-avatar-api/llms.txt) - [OpenAPI document](https://skmtc.dev/liveavatar/apis/live-avatar-api/revisions/8bc38e64ff31?raw)