> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt > Use this file to discover all available pages before exploring further. # Design a Voice > Returns up to 3 voices matching a natural language description (e.g. 'warm, confident female narrator'). Use the seed parameter to get different batches of results. ## OpenAPI ````yaml /openapi/external-api.json post /v3/voices openapi: 3.1.0 info: title: HeyGen External API version: 1.0.0 description: >- HeyGen's external API for programmatic AI video creation. See https://docs.heygen.com for full documentation. contact: name: HeyGen Product Infra url: https://heygen.com servers: - url: https://api.heygen.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Video Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: User description: Account information and billing - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) paths: /v3/voices: post: tags: - Voices summary: Design a Voice description: >- Returns up to 3 voices matching a natural language description (e.g. 'warm, confident female narrator'). Use the seed parameter to get different batches of results. operationId: designVoice requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DesignVoiceRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DesignVoiceResponseData' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: '''prompt'' is required.' param: prompt doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: authentication_failed message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: rate_limit_exceeded message: >- Too many requests. Retry after the duration specified in the Retry-After header. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying schema: type: integer security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: DesignVoiceRequest: additionalProperties: false description: Request body for POST /v3/voices — design a voice via semantic search. properties: prompt: description: >- Natural language description of the desired voice (e.g., 'warm, confident female narrator'). maxLength: 1000 minLength: 1 title: Prompt type: string gender: anyOf: - type: string - type: 'null' default: null description: 'Filter by gender: ''male'' or ''female''.' title: Gender locale: anyOf: - type: string - type: 'null' default: null description: BCP-47 locale tag to filter by (e.g., 'en-US', 'pt-BR'). title: Locale seed: default: 0 description: >- Controls which batch of results to return. seed=0 returns the top matches, seed=1 the next batch, etc. Same prompt + seed always returns the same voices. minimum: 0 title: Seed type: integer required: - prompt title: DesignVoiceRequest type: object DesignVoiceResponseData: description: Response payload for POST /v3/voices. properties: voices: description: Matching voices for the given prompt, ordered by relevance. items: $ref: '#/components/schemas/AudioVoiceItem' title: Voices type: array seed: description: The seed used for this request. Increment to get different voices. title: Seed type: integer required: - voices - seed title: DesignVoiceResponseData type: object StandardAPIError: type: object properties: code: type: string description: Machine-readable error code example: invalid_parameter message: type: string description: Human-readable error message example: Video not found param: type: - string - 'null' description: Which request field caused the error doc_url: type: - string - 'null' description: Link to error documentation required: - code - message AudioVoiceItem: description: A single voice in the listing response. properties: voice_id: description: Unique voice identifier. examples: - 1bd001e7e50f421d891986aad5c8bbd2 title: Voice Id type: string name: description: Display name of the voice. examples: - Sara title: Name type: string language: description: Primary language of the voice. examples: - English title: Language type: string gender: description: Gender of the voice. examples: - female title: Gender type: string preview_audio_url: anyOf: - type: string - type: 'null' default: null description: URL to a short audio preview of the voice. examples: - https://files.heygen.ai/voice/preview_sara.mp3 title: Preview Audio Url support_pause: description: Whether the voice supports SSML pause/break tags. examples: - true title: Support Pause type: boolean support_locale: description: Whether the voice supports locale variants. examples: - true title: Support Locale type: boolean type: $ref: '#/components/schemas/AudioVoiceType' description: Whether this is a public or private voice. examples: - public required: - voice_id - name - language - gender - support_pause - support_locale - type title: AudioVoiceItem type: object AudioVoiceType: enum: - public - private title: AudioVoiceType type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: HeyGen API key. Obtain from your HeyGen dashboard. BearerAuth: type: http scheme: bearer description: OAuth2 bearer token. ````