> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Search audio (music or sound effects) > Semantically search the audio catalog by natural-language description — set type=music (the default) for background music (e.g. 'upbeat lofi hip-hop', 'tense cinematic riser') or type=sound_effects for SFX (e.g. 'whoosh for a scene change', 'cash register cha-ching'). Returns tracks ranked by similarity, each with a pre-signed download URL, plus cursor-based pagination. ## OpenAPI ````yaml /openapi/external-api.json get /v3/audio/sounds 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: Templates description: Generate videos from reusable templates by replacing their variables - 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: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions - name: Batches description: Create and track batches of videos. - name: Video Translation Batches description: Create and track batches of video translations. - name: Lipsync Batches description: Create and track batches of lipsyncs. - name: Asset Batches description: Create and track batches of direct-to-S3 asset uploads. - name: User description: Account information and billing - name: Avatars description: List and manage avatars and looks - name: Avatar Realtime description: >- Low-latency streaming avatar sessions — create a stream, poll for its HLS URL, push text, consume per-word timestamps - 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) - name: HyperFrames description: Render HyperFrames composition zips into video — separate from /v3/videos - name: Filler Word Removal description: '' paths: /v3/audio/sounds: get: tags: - Audio summary: Search audio (music or sound effects) description: >- Semantically search the audio catalog by natural-language description — set type=music (the default) for background music (e.g. 'upbeat lofi hip-hop', 'tense cinematic riser') or type=sound_effects for SFX (e.g. 'whoosh for a scene change', 'cash register cha-ching'). Returns tracks ranked by similarity, each with a pre-signed download URL, plus cursor-based pagination. operationId: searchAudioSounds parameters: - name: query in: query required: true description: >- Natural-language description of the audio you want, e.g. 'upbeat lofi hip-hop' or 'tense cinematic riser'. Results are ranked by semantic similarity to this text. schema: type: string minLength: 1 maxLength: 5000 - name: type in: query required: false description: >- Audio content type to search: 'music' (background-music catalog) or 'sound_effects' (SFX catalog). Defaults to 'music'. schema: type: string enum: - music - sound_effects default: music - name: limit in: query required: false description: Maximum number of results to return (1-50). schema: type: integer minimum: 1 maximum: 50 default: 10 - name: min_score in: query required: false description: >- Minimum semantic similarity score (0-1). Tracks scoring below this are omitted. schema: type: number minimum: 0 maximum: 1 default: 0.7 - name: token in: query required: false description: >- Opaque cursor token for the next page, taken from 'next_token' in a prior response. schema: type: string responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AudioSoundItem' has_more: type: boolean description: Whether more pages are available next_token: type: - string - 'null' description: Opaque cursor for the next page '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: '''query'' is required.' param: query 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: AudioSoundItem: description: A single audio track in the catalog search response. properties: id: description: Unique identifier for the audio track. examples: - rev_abc123 title: Id type: string name: description: Display name of the audio track. examples: - Upbeat Lofi Loop title: Name type: string description: description: Semantic description the track was indexed under. examples: - Jazz, happy, jazzy, upbeat, rhythmic title: Description type: string audio_url: description: >- Temporary pre-signed URL to download the audio file. Expires; do not cache long-term. examples: - https://files.heygen.ai/audio/music_abc123.mp3 title: Audio Url type: string duration: anyOf: - type: number - type: 'null' default: null description: Duration of the audio in seconds, when known. examples: - 120 title: Duration peak_offset: anyOf: - type: number - type: 'null' default: null description: >- For sound effects, seconds from clip start to the loudest RMS peak. Null for tracks without placement metadata. examples: - 0.37 title: Peak Offset placement: anyOf: - type: string - type: 'null' default: null description: >- For sound effects, suggested placement mode: 'hit', 'riser', or 'bed'. Null for tracks without placement metadata. examples: - hit title: Placement score: description: Semantic similarity score (0-1); higher means a closer match. examples: - 0.83 title: Score type: number type: $ref: '#/components/schemas/AudioContentType' description: Audio content type of this track. examples: - music required: - id - name - description - audio_url - score - type title: AudioSoundItem 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 AudioContentType: description: >- Audio content type for catalog search. Each value maps to its own Pinecone namespace (see music_search._NAMESPACE_BY_TYPE). enum: - music - sound_effects title: AudioContentType 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. ````