Skip to main content
GET
/
api
/
v1
/
voice-templates
# Request 1: Get all voice templates
curl -X GET "https://app.talkover.ai/api/v1/voice-templates" \
  -H "Authorization: Bearer talq_your_environment_token_here"

{
  "success": true,
  "data": [
    {
      "display_name": "Bianca",
      "voices": [
        {
          "id": "voice-template-uuid-1",
          "name": "Bianca",
          "gender": "female",
          "language": "pt-BR",
          "quality_tier": "basic",
          "cost": "0.10"
        },
        {
          "id": "voice-template-uuid-2",
          "name": "Bianca",
          "gender": "female",
          "language": "pt-BR",
          "quality_tier": "pro",
          "cost": "0.16"
        },
        {
          "id": "voice-template-uuid-3",
          "name": "Bianca",
          "gender": "female",
          "language": "pt-BR",
          "quality_tier": "ultra",
          "cost": "0.23"
        }
      ]
    },
    {
      "display_name": "Isabela",
      "voices": [
        {
          "id": "voice-template-uuid-4",
          "name": "Isabela",
          "gender": "female",
          "language": "pt-BR",
          "quality_tier": "basic",
          "cost": "0.10"
        },
        {
          "id": "voice-template-uuid-5",
          "name": "Isabela",
          "gender": "female",
          "language": "pt-BR",
          "quality_tier": "pro",
          "cost": "0.16"
        }
      ]
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
List Voice Templates

Retrieve a list of available voice templates grouped by display name. This endpoint returns voice templates with different quality tiers and languages that can be used for voice agents.

​
Endpoint

GET /api/v1/voice-templates

​
Request Headers

​
Authorization
string
required
Bearer token for authentication. Format: Bearer talq_your_environment_token_here

​
Query Parameters

​
language
string
Filter by language (e.g., en-US, pt-BR)
​
quality_tier
string
Filter by quality tier. Options: basic, pro, ultra, beta
​
gender
string
Filter by gender. Options: male, female

​
Example Requests

# Request 1: Get all voice templates
curl -X GET "https://app.talkover.ai/api/v1/voice-templates" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Request 2: Get Portuguese voice templates
curl -X GET "https://app.talkover.ai/api/v1/voice-templates?language=pt-BR" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Request 3: Get female pro quality templates
curl -X GET "https://app.talkover.ai/api/v1/voice-templates?gender=female&quality_tier=pro" \
  -H "Authorization: Bearer talq_your_environment_token_here"

​
Response

​
Success Response (200 OK)

{
  "success": true,
  "data": [
    {
      "display_name": "Bianca",
      "voices": [
        {
          "id": "voice-template-uuid-1",
          "name": "Bianca",
          "gender": "female",
          "language": "pt-BR",
          "quality_tier": "basic",
          "cost": "0.10"
        },
        {
          "id": "voice-template-uuid-2",
          "name": "Bianca",
          "gender": "female",
          "language": "pt-BR",
          "quality_tier": "pro",
          "cost": "0.16"
        },
        {
          "id": "voice-template-uuid-3",
          "name": "Bianca",
          "gender": "female",
          "language": "pt-BR",
          "quality_tier": "ultra",
          "cost": "0.23"
        }
      ]
    },
    {
      "display_name": "Isabela",
      "voices": [
        {
          "id": "voice-template-uuid-4",
          "name": "Isabela",
          "gender": "female",
          "language": "pt-BR",
          "quality_tier": "basic",
          "cost": "0.10"
        },
        {
          "id": "voice-template-uuid-5",
          "name": "Isabela",
          "gender": "female",
          "language": "pt-BR",
          "quality_tier": "pro",
          "cost": "0.16"
        }
      ]
    }
  ]
}

​
Response Fields

​
success
boolean
required
Indicates if the operation was successful.
​
data
array
required
Array of voice template groups.

​
Error Responses

​
401 Unauthorized

{
  "success": false,
  "message": "Unauthorized"
}

​
422 Validation Error

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "language": [
      "The selected language is invalid."
    ],
    "quality_tier": [
      "The selected quality tier is invalid."
    ],
    "gender": [
      "The selected gender is invalid."
    ]
  }
}

​
500 Server Error

{
  "success": false,
  "message": "Internal server error."
}

​
Error Codes

CodeDescriptionHTTP Status
INVALID_TOKENAuthentication token is invalid or missing401
VALIDATION_ERRORQuery parameter validation failed422
SERVER_ERRORInternal server error occurred500

​
Important Notes

Grouped by display name. Voice templates are grouped by their display name, with each group containing different quality tiers of the same voice.
Quality tiers affect cost. Higher quality tiers (pro, ultra) cost more per minute than basic tiers.
Language filtering. Use the language parameter to get voice templates for specific languages.

​
Best Practices

  1. Filter by language - Use the language parameter to get relevant voice templates
  2. Consider quality vs cost - Balance voice quality with cost requirements
  3. Test voices - Use the demo endpoint to test voice templates before selecting
  4. Cache results - Voice templates don’t change frequently, so consider caching
  5. Handle empty responses - Some language/gender combinations may return empty results
  • Generate Voice Template Demo: GET /api/v1/voice-templates/{voiceTemplate}/demo
  • List Phone Numbers: GET /api/v1/phone-numbers