> ## 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.

# Stream Speech

> Generates speech as Server-Sent Events. Audio events contain ordered base64-encoded standalone WAV parts; alignment events are included only when `with_timestamps` is true. A clean stream ends with `data: [DONE]`. The voice identified by `voice_id` must be an ACTIVE professional voice. Rate limit: 30 requests per minute per workspace member.



## OpenAPI

````yaml /openapi/external-api.json post /v3/models/audio/tts/stream
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: 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/tts/stream:
    post:
      tags:
        - Models
      summary: Stream Speech
      description: >-
        Generates speech as Server-Sent Events. Audio events contain ordered
        base64-encoded standalone WAV parts; alignment events are included only
        when `with_timestamps` is true. A clean stream ends with `data: [DONE]`.
        The voice identified by `voice_id` must be an ACTIVE professional voice.
        Rate limit: 30 requests per minute per workspace member.
      operationId: streamModelSpeech
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamSpeechRequest'
      responses:
        '200':
          description: >-
            Server-Sent Events stream. Each `data:` frame contains an audio,
            alignment, or terminal error event; a clean stream terminates with
            `data: [DONE]`.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SpeechStreamEvent'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              examples:
                invalid_parameter:
                  summary: Unsupported language
                  value:
                    error:
                      code: invalid_parameter
                      message: language is not a supported language.
                      param: language
                      doc_url: null
                voice_expired:
                  summary: Professional voice clone over the workspace slot limit
                  value:
                    error:
                      code: voice_expired
                      message: >-
                        Professional voice clone 'voice-1' expired because this
                        workspace exceeded its professional voice clone slot
                        limit of 2. Purchase more professional voice clone
                        slots, or delete other professional voice clones to
                        bring the workspace within its limit, then try again.
                      param: null
                      doc_url: null
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: unauthorized
                  message: API key or OAuth token required
                  param: null
                  doc_url: null
        '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 in the selected billing wallet
                  value:
                    error:
                      code: insufficient_credit
                      message: >-
                        Insufficient credits. Please upgrade your plan or
                        purchase additional credits.
                      param: null
                      doc_url: null
                plan_upgrade_required:
                  summary: OAuth speech requires a paid plan
                  value:
                    error:
                      code: plan_upgrade_required
                      message: >-
                        Professional voice speech through OAuth requires a paid
                        plan. Please upgrade your subscription.
                      param: null
                      doc_url: null
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: forbidden
                  message: >-
                    The professional voice cloning API is not enabled for this
                    account.
                  param: null
                  doc_url: null
        '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`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              examples:
                voice_not_ready:
                  summary: Voice training is not complete
                  value:
                    error:
                      code: voice_not_ready
                      message: The professional voice clone is not ready for inference.
                      param: null
                      doc_url: null
                voice_training_failed:
                  summary: Voice training failed
                  value:
                    error:
                      code: voice_training_failed
                      message: The professional voice clone failed training.
                      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
        '502':
          description: >-
            Upstream dependency failed — 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: voice_provider_error
                  message: The upstream voice provider failed. Retry the request.
                  param: null
                  doc_url: null
        '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: Voice inference is temporarily busy. Retry the request.
                  param: null
                  doc_url: null
        '504':
          description: >-
            Upstream dependency timed out — 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: gateway_timeout
                  message: The upstream voice provider timed out. Retry the request.
                  param: null
                  doc_url: null
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    StreamSpeechRequest:
      additionalProperties: false
      properties:
        voice_id:
          description: Identifier of the voice used for speech synthesis.
          minLength: 1
          title: Voice Id
          type: string
        text:
          description: Plain text to synthesize. SSML and break tags are not supported.
          maxLength: 5000
          minLength: 1
          title: Text
          type: string
        language:
          description: Language code used for speech synthesis, such as `en`.
          minLength: 1
          title: Language
          type: string
        seed:
          anyOf:
            - maximum: 4294967295
              minimum: 0
              type: integer
            - type: 'null'
          default: null
          description: Optional best-effort deterministic generation seed.
          title: Seed
        with_timestamps:
          default: false
          description: Whether to include word-timestamp events in the response stream.
          title: With Timestamps
          type: boolean
      required:
        - voice_id
        - text
        - language
      title: StreamSpeechRequest
      type: object
    SpeechStreamEvent:
      description: One JSON event carried by the speech SSE stream.
      discriminator:
        mapping:
          alignment:
            $ref: '#/components/schemas/SpeechAlignmentEvent'
          audio:
            $ref: '#/components/schemas/SpeechAudioEvent'
          error:
            $ref: '#/components/schemas/SpeechErrorEvent'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/SpeechAudioEvent'
        - $ref: '#/components/schemas/SpeechAlignmentEvent'
        - $ref: '#/components/schemas/SpeechErrorEvent'
      title: SpeechStreamEvent
    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'
      required:
        - code
        - message
    SpeechAlignmentEvent:
      properties:
        type:
          const: alignment
          description: Event type.
          title: Type
          type: string
        word_alignments:
          description: Word-level timing information for the generated speech.
          items:
            $ref: '#/components/schemas/SpeechWordAlignment'
          minItems: 1
          title: Word Alignments
          type: array
      required:
        - type
        - word_alignments
      title: SpeechAlignmentEvent
      type: object
    SpeechAudioEvent:
      properties:
        type:
          const: audio
          description: Event type.
          title: Type
          type: string
        part_index:
          description: Zero-based sequence number of this audio part.
          minimum: 0
          title: Part Index
          type: integer
        audio:
          description: Base64-encoded standalone WAV audio part.
          title: Audio
          type: string
      required:
        - type
        - part_index
        - audio
      title: SpeechAudioEvent
      type: object
    SpeechErrorEvent:
      properties:
        type:
          const: error
          description: Event type.
          title: Type
          type: string
        detail:
          description: >-
            Sanitized description of a failure that occurred after streaming
            began.
          title: Detail
          type: string
      required:
        - type
        - detail
      title: SpeechErrorEvent
      type: object
    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
    SpeechWordAlignment:
      properties:
        text:
          description: Word represented by this alignment entry.
          minLength: 1
          title: Text
          type: string
        start_time:
          description: Word start time in seconds.
          minimum: 0
          title: Start Time
          type: number
        end_time:
          description: Word end time in seconds.
          minimum: 0
          title: End Time
          type: number
        confidence:
          description: Alignment confidence from 0 to 1.
          maximum: 1
          minimum: 0
          title: Confidence
          type: number
      required:
        - text
        - start_time
        - end_time
        - confidence
      title: SpeechWordAlignment
      type: object
  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.

````