> ## 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. # Convert Speech > Convert a recording into an ACTIVE instant voice in your workspace. Professional voice clones are not supported. The words and timing stay the same. The response contains one WAV URL and its duration in seconds. Use an API key with voices:write or an OAuth bearer token. OAuth requires a paid plan. The limit is 30 requests per minute per workspace member. The source can contain up to 300 seconds of audio. Use a public HTTPS URL, an uploaded asset, or base64 audio. URL downloads must finish within 60 seconds. Set a client timeout of at least 160 seconds. The optional model_id defaults to heygen-voice-sts-0. The optional seed requests best-effort repeatable generation. Set remove_background_noise to true to clean the source before conversion. This adds latency. Send Idempotency-Key for safe retries. The same key and body replay the completed result without another charge for 24 hours. Keys are scoped to the workspace and this endpoint. A running request returns 409 request_in_progress. A different body with the same key returns 409 conflict. A keyed request continues after a client disconnect and can still be charged. Without a key, a disconnect before the charge cancels the request without a charge. After a timeout, wait before retrying with the same key. The conversion can still be running. ## OpenAPI ````yaml /openapi/external-api.json post /v3/models/audio/sts 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: API Keys description: Inspect the API key authenticating the current request - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Folders description: >- Create folders to organize videos and translations in the workspace, and look up any folder, Assets library folders included, by id - 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: Models description: '' - name: Filler Word Removal description: '' paths: /v3/models/audio/sts: post: tags: - Models summary: Convert Speech description: >- Convert a recording into an ACTIVE instant voice in your workspace. Professional voice clones are not supported. The words and timing stay the same. The response contains one WAV URL and its duration in seconds. Use an API key with voices:write or an OAuth bearer token. OAuth requires a paid plan. The limit is 30 requests per minute per workspace member. The source can contain up to 300 seconds of audio. Use a public HTTPS URL, an uploaded asset, or base64 audio. URL downloads must finish within 60 seconds. Set a client timeout of at least 160 seconds. The optional model_id defaults to heygen-voice-sts-0. The optional seed requests best-effort repeatable generation. Set remove_background_noise to true to clean the source before conversion. This adds latency. Send Idempotency-Key for safe retries. The same key and body replay the completed result without another charge for 24 hours. Keys are scoped to the workspace and this endpoint. A running request returns 409 request_in_progress. A different body with the same key returns 409 conflict. A keyed request continues after a client disconnect and can still be charged. Without a key, a disconnect before the charge cancels the request without a charge. After a timeout, wait before retrying with the same key. The conversion can still be running. operationId: convertModelSpeech parameters: - name: Idempotency-Key in: header required: false description: >- Optional key, scoped to the workspace and this endpoint. The same key and body replay the result for 24 hours without another charge. A different body returns 409 conflict. A running request returns 409 request_in_progress. schema: type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ maxLength: 255 minLength: 1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSpeechConversionRequest' responses: '200': description: >- Converted speech. The audio_url points to a WAV. Duration is in seconds and matches the source. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateSpeechConversionResponseData' headers: X-Request-Id: description: The request identifier. Use this ID when you contact support. schema: type: string '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: >- The audio must contain valid speech and must not exceed 300 seconds. param: audio doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: unauthorized message: An API key or OAuth token is required. '402': description: >- Payment required — `error.code` is one of: `insufficient_credit`, `plan_upgrade_required`. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' examples: insufficient_credit: summary: Insufficient credits value: error: code: insufficient_credit message: The balance does not cover the source duration. param: null doc_url: null plan_upgrade_required: summary: OAuth requires a paid plan value: error: code: plan_upgrade_required message: OAuth speech conversion requires a paid plan. '403': description: >- Forbidden — `error.code` is one of: `insufficient_api_key_scope`, `resource_access_denied`. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' examples: insufficient_api_key_scope: summary: Missing scope value: error: code: insufficient_api_key_scope message: The API key requires voices:write. resource_access_denied: summary: Role has no API access value: error: code: resource_access_denied message: Your role does not permit API access. '404': description: Resource not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: voice_not_found message: Voice not found. param: null doc_url: null '409': description: >- Conflict — `error.code` is one of: `voice_not_ready`, `voice_training_failed`, `request_in_progress`, `conflict`. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' examples: voice_not_ready: summary: Voice preparation is incomplete value: error: code: voice_not_ready message: Retry after the Retry-After delay. param: null doc_url: null voice_training_failed: summary: Voice creation failed value: error: code: voice_training_failed message: Use another voice. param: null doc_url: null request_in_progress: summary: A request with this key is running value: error: code: request_in_progress message: Retry after the Retry-After delay. param: null doc_url: null conflict: summary: The key was used with another body value: error: code: conflict message: Use a new key for a new request. param: null doc_url: null headers: Retry-After: description: Seconds to wait for voice_not_ready or request_in_progress. schema: type: integer '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 '500': content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: internal_error message: The conversion failed. description: Conversion failed, or an unexpected error occurred. '503': description: >- Temporarily unavailable — the request did not complete and is safe to retry. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: service_unavailable message: >- Conversion is unavailable, or the source download timed out. Retry after the Retry-After delay. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer '504': description: >- Conversion exceeded 150 seconds. It can still be running. Wait before retrying with the same key. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: gateway_timeout message: >- Conversion exceeded 150 seconds. It can still be running. Wait before retrying with the same key. param: null doc_url: null security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: CreateSpeechConversionRequest: additionalProperties: false properties: voice_id: description: >- Identifier of the voice to speak in: a voice clone the caller's workspace owns. maxLength: 256 minLength: 1 title: Voice Id type: string audio: description: >- Source speech as a public HTTPS URL, an uploaded asset, or base64 audio. The duration limit is 300 seconds. Size limits: 32 MB by URL or 100 MB as an asset. Base64 audio has a 16 MB limit. discriminator: mapping: asset_id: '#/components/schemas/AssetId' base64: '#/components/schemas/AssetBase64' url: '#/components/schemas/AssetUrl' propertyName: type oneOf: - $ref: '#/components/schemas/AssetUrl' - $ref: '#/components/schemas/AssetId' - $ref: '#/components/schemas/AssetBase64' title: Audio remove_background_noise: default: false description: >- Remove background noise from the source before converting it. This adds latency. title: Remove Background Noise type: boolean seed: anyOf: - maximum: 4294967295 minimum: 0 type: integer - type: 'null' default: null description: Optional best-effort deterministic generation seed. title: Seed model_id: anyOf: - $ref: '#/components/schemas/SpeechConversionModel' - type: 'null' default: null description: >- The speech-to-speech model. `heygen-voice-sts-0` is the only one, and the default. required: - voice_id - audio title: CreateSpeechConversionRequest type: object CreateSpeechConversionResponseData: properties: audio_url: description: URL of the converted WAV audio file. title: Audio Url type: string duration: description: Audio duration in seconds. This matches the source duration. minimum: 0 title: Duration type: number required: - audio_url - duration title: CreateSpeechConversionResponseData 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 errors: type: array description: >- Per-item error details for batch/multi-node failures (e.g. graph compilation errors by node). items: $ref: '#/components/schemas/StandardAPIErrorDetail' request_id: type: string description: >- Request identifier, also returned in the X-HeyGen-Request-Id response header. Include it when contacting support. example: 8c4f0b9e1d2a4f6b9e3c7a1d5f2b8e40 required: - code - message AssetId: additionalProperties: false description: Asset input via HeyGen asset ID from the asset upload endpoint. properties: type: const: asset_id description: Input type discriminator title: Type type: string asset_id: description: HeyGen asset ID from the asset upload endpoint title: Asset Id type: string required: - type - asset_id title: AssetId type: object AssetBase64: additionalProperties: false description: Asset input via base64-encoded content. properties: type: const: base64 description: Input type discriminator title: Type type: string media_type: description: MIME type of the encoded content (e.g. "image/png") title: Media Type type: string data: description: Base64-encoded file content title: Data type: string required: - type - media_type - data title: AssetBase64 type: object x-mcp-visible: false AssetUrl: additionalProperties: false description: Asset input via publicly accessible HTTPS URL. properties: type: const: url description: Input type discriminator title: Type type: string url: description: Publicly accessible HTTPS URL for the asset title: Url type: string required: - type - url title: AssetUrl type: object SpeechConversionModel: description: 'Speech-to-speech models: the same speech, spoken in another voice.' enum: - heygen-voice-sts-0 title: SpeechConversionModel type: string StandardAPIErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: unknown_node_type message: type: string description: Human-readable error message example: Unknown node type node_id: type: string description: Graph node id this error pertains to, if applicable port: type: string description: Port name on the node this error pertains to, if applicable path: type: string description: Field path within the item this error pertains to, if applicable required: - code - message 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.