> ## Documentation Index > Fetch the complete documentation index at: https://docs.talking-avatar.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create a voice agent ## OpenAPI ````yaml /api-reference/openapi.json post /voice-agents openapi: 3.1.0 info: title: Talking Avatar API version: '1' description: >- Your account from your server, with an API key: voice agents, calls, knowledge bases, links, usage and billing. Send API-Version: 1 to pin version 1. servers: - url: https://backend.talking-avatar.dev/api/talking-avatar security: - apiKey: [] paths: /voice-agents: post: summary: Create a voice agent parameters: - name: API-Version in: header description: 'The API version. Without it: 1.' schema: type: string enum: - '1' requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 120 description: Shown to callers on the call page enabled: type: boolean default: true description: It takes calls access: type: string enum: - public - private description: >- public (new agents): anyone with its share link can call. private: only through its links. config: type: object description: Its settings, as in the dashboard's agent editor properties: avatar: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ description: An avatar ID, such as ava6, or a custom avatar's voice: type: string description: 'A voice ID: copy it from an agent made in the dashboard' instructions: type: string minLength: 1 maxLength: 20000 description: >- The prompt: who the agent is, how it speaks and what it knows greeting: type: string maxLength: 500 default: '' description: 'The first message. Empty: the caller speaks first.' vad: type: string enum: - semantic - server default: semantic description: 'Turn-taking: semantic, or server (voice activity)' eagerness: type: string enum: - auto - low - medium - high default: auto description: >- Semantic turn-taking's eagerness: auto, low (patient), medium (balanced), high (eager) vadThreshold: type: number minimum: 0 maximum: 1 default: 0.5 description: 'Voice activity: sensitivity threshold' prefixPaddingMs: type: integer minimum: 0 maximum: 2000 default: 300 description: 'Voice activity: prefix padding' silenceDurationMs: type: integer minimum: 100 maximum: 3000 default: 500 description: 'Voice activity: the silence that ends a turn' interruptible: type: boolean default: true description: Callers can interrupt noiseReduction: type: string enum: - near_field - far_field - 'off' default: near_field reasoningEffort: type: string enum: - minimal - low - medium - high default: low description: Reasoning speed: type: number minimum: 0.25 maximum: 1.5 default: 1 description: Speaking speed maxDurationMinutes: type: integer minimum: 1 maximum: 60 default: 10 description: Maximum call length endCall: type: boolean default: true description: The built-in End call tool tools: type: array maxItems: 20 default: [] description: 'Your tools: HTTPS endpoints the agent calls' items: type: object properties: name: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ not: const: end_call description: >- The function name. Unique among its tools and knowledge bases. description: type: string minLength: 1 maxLength: 1000 description: 'When to use it: the agent reads this' parameters: type: object properties: type: const: object required: - type description: Its arguments, as a JSON Schema object url: type: string maxLength: 2000 pattern: ^https:// description: Your endpoint headers: type: object maxProperties: 10 propertyNames: pattern: ^[A-Za-z0-9-]{1,64}$ additionalProperties: type: string maxLength: 2000 default: {} description: >- Sent with every request, such as your endpoint's auth required: - name - description - parameters - url additionalProperties: false knowledgeBaseIds: type: array maxItems: 10 uniqueItems: true default: [] items: type: string format: uuid description: Your knowledge bases it answers from, by ID webhookUrl: type: string maxLength: 2000 pattern: ^(https://.+)?$ default: '' description: 'Your post-call webhook. Empty: none.' required: - avatar - voice - instructions additionalProperties: false required: - name - config additionalProperties: false example: name: Maya access: private config: avatar: ava6 voice: VOICE_ID instructions: >- You are Maya, a friendly support agent for Acme. Help callers track their orders and answer questions about returns. greeting: Hi, this is Maya from Acme. How can I help? webhookUrl: https://example.com/talking-avatar/call-ended responses: '201': description: Success content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid description: The agent's ID name: type: string description: Shown to callers enabled: type: boolean description: It takes calls access: type: string enum: - public - private description: >- public: anyone with its share link can call. private: only through its links. config: type: object description: Its settings, as in the dashboard's agent editor properties: avatar: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ description: An avatar ID, such as ava6, or a custom avatar's voice: type: string description: >- A voice ID: copy it from an agent made in the dashboard instructions: type: string minLength: 1 maxLength: 20000 description: >- The prompt: who the agent is, how it speaks and what it knows greeting: type: string maxLength: 500 default: '' description: 'The first message. Empty: the caller speaks first.' vad: type: string enum: - semantic - server default: semantic description: 'Turn-taking: semantic, or server (voice activity)' eagerness: type: string enum: - auto - low - medium - high default: auto description: >- Semantic turn-taking's eagerness: auto, low (patient), medium (balanced), high (eager) vadThreshold: type: number minimum: 0 maximum: 1 default: 0.5 description: 'Voice activity: sensitivity threshold' prefixPaddingMs: type: integer minimum: 0 maximum: 2000 default: 300 description: 'Voice activity: prefix padding' silenceDurationMs: type: integer minimum: 100 maximum: 3000 default: 500 description: 'Voice activity: the silence that ends a turn' interruptible: type: boolean default: true description: Callers can interrupt noiseReduction: type: string enum: - near_field - far_field - 'off' default: near_field reasoningEffort: type: string enum: - minimal - low - medium - high default: low description: Reasoning speed: type: number minimum: 0.25 maximum: 1.5 default: 1 description: Speaking speed maxDurationMinutes: type: integer minimum: 1 maximum: 60 default: 10 description: Maximum call length endCall: type: boolean default: true description: The built-in End call tool tools: type: array maxItems: 20 default: [] description: 'Your tools: HTTPS endpoints the agent calls' items: type: object properties: name: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ not: const: end_call description: >- The function name. Unique among its tools and knowledge bases. description: type: string minLength: 1 maxLength: 1000 description: 'When to use it: the agent reads this' parameters: type: object properties: type: const: object required: - type description: Its arguments, as a JSON Schema object url: type: string maxLength: 2000 pattern: ^https:// description: Your endpoint headers: type: object maxProperties: 10 propertyNames: pattern: ^[A-Za-z0-9-]{1,64}$ additionalProperties: type: string maxLength: 2000 default: {} description: >- Sent with every request, such as your endpoint's auth required: - name - description - parameters - url additionalProperties: false knowledgeBaseIds: type: array maxItems: 10 uniqueItems: true default: [] items: type: string format: uuid description: Your knowledge bases it answers from, by ID webhookUrl: type: string maxLength: 2000 pattern: ^(https://.+)?$ default: '' description: 'Your post-call webhook. Empty: none.' required: - avatar - voice - instructions additionalProperties: false created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name - enabled - access - config - created_at - updated_at additionalProperties: false code: type: integer const: 201 message: type: string required: - data - code 4XX: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' 5XX: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: bash label: cURL source: >- curl -X POST https://backend.talking-avatar.dev/api/talking-avatar/voice-agents \ -H "Authorization: Bearer $TALKING_AVATAR_API_KEY" \ -H "API-Version: 1" \ -H "Content-Type: application/json" \ -d '{ "name": "Maya", "access": "private", "config": { "avatar": "ava6", "voice": "VOICE_ID", "instructions": "You are Maya, a friendly support agent for Acme. Help callers track their orders and answer questions about returns.", "greeting": "Hi, this is Maya from Acme. How can I help?", "webhookUrl": "https://example.com/talking-avatar/call-ended" } }' - lang: python label: Python source: |- import os, requests response = requests.post( "https://backend.talking-avatar.dev/api/talking-avatar/voice-agents", headers={ "Authorization": f"Bearer {os.environ['TALKING_AVATAR_API_KEY']}", "API-Version": "1", }, json={ "name": "Maya", "access": "private", "config": { "avatar": "ava6", "voice": "VOICE_ID", "instructions": "You are Maya, a friendly support agent for Acme. Help callers track their orders and answer questions about returns.", "greeting": "Hi, this is Maya from Acme. How can I help?", "webhookUrl": "https://example.com/talking-avatar/call-ended", }, }, ) response.raise_for_status() data = response.json()["data"] - lang: javascript label: Node.js source: >- const response = await fetch("https://backend.talking-avatar.dev/api/talking-avatar/voice-agents", { method: "POST", headers: { Authorization: `Bearer ${process.env.TALKING_AVATAR_API_KEY}`, "API-Version": "1", "Content-Type": "application/json", }, body: JSON.stringify({ "name": "Maya", "access": "private", "config": { "avatar": "ava6", "voice": "VOICE_ID", "instructions": "You are Maya, a friendly support agent for Acme. Help callers track their orders and answer questions about returns.", "greeting": "Hi, this is Maya from Acme. How can I help?", "webhookUrl": "https://example.com/talking-avatar/call-ended" } }), }); const { data } = await response.json(); components: schemas: Error: type: object properties: code: type: integer description: The HTTP status message: type: string description: What went wrong, readable data: type: 'null' required: - code additionalProperties: false securitySchemes: apiKey: type: http scheme: bearer description: Your API key, tav_… x-default: YOUR_API_KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.