> ## 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. # Create Avatar Realtime Session > Start a low-latency streaming avatar session and return a `stream_id`. Three modes, selected by the `type` discriminator: `tts` (speak a fixed script), `audio` (drive lip-sync from a pre-existing audio asset), and `text_stream` (seed with initial text, then append more text deltas over time via POST /v3/avatar-realtime/{stream_id}/text — e.g. as an upstream LLM streams tokens). Poll GET /v3/avatar-realtime/{stream_id} for the session status and HLS playback URL. ## OpenAPI ````yaml /openapi/external-api.json post /v3/avatar-realtime 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: 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: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions paths: /v3/avatar-realtime: post: tags: - Avatar Realtime summary: Create Avatar Realtime Session description: >- Start a low-latency streaming avatar session and return a `stream_id`. Three modes, selected by the `type` discriminator: `tts` (speak a fixed script), `audio` (drive lip-sync from a pre-existing audio asset), and `text_stream` (seed with initial text, then append more text deltas over time via POST /v3/avatar-realtime/{stream_id}/text — e.g. as an upstream LLM streams tokens). Poll GET /v3/avatar-realtime/{stream_id} for the session status and HLS playback URL. operationId: createAvatarRealtimeSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAvatarRealtimeRequestBody' responses: '201': description: Created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateAvatarRealtimeResponse' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: 'Invalid ''type''. Must be one of: tts, audio, text_stream.' param: type 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: CreateAvatarRealtimeRequestBody: description: Discriminated union for POST /v3/avatar-realtime request body. discriminator: mapping: audio: $ref: '#/components/schemas/CreateAvatarRealtimeAudio' text_stream: $ref: '#/components/schemas/CreateAvatarRealtimeTextStream' tts: $ref: '#/components/schemas/CreateAvatarRealtimeTTS' propertyName: type oneOf: - $ref: '#/components/schemas/CreateAvatarRealtimeTTS' - $ref: '#/components/schemas/CreateAvatarRealtimeAudio' - $ref: '#/components/schemas/CreateAvatarRealtimeTextStream' title: CreateAvatarRealtimeRequestBody CreateAvatarRealtimeResponse: description: Response data for POST /v3/avatar-realtime. properties: stream_id: description: >- Unique streaming session identifier. Use with GET /v3/avatar-realtime/{stream_id} to poll status. title: Stream Id type: string required: - stream_id title: CreateAvatarRealtimeResponse 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 CreateAvatarRealtimeAudio: additionalProperties: false description: Create a stream with a pre-existing audio asset. properties: type: const: audio description: 'Audio source type: pre-existing audio file.' title: Type type: string avatar_id: description: HeyGen photo avatar or motion avatar look ID. title: Avatar Id type: string audio: description: Audio file input (URL, asset ID, or base64). discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' base64: $ref: '#/components/schemas/AssetBase64' url: $ref: '#/components/schemas/AssetUrl' propertyName: type oneOf: - $ref: '#/components/schemas/AssetUrl' - $ref: '#/components/schemas/AssetId' - $ref: '#/components/schemas/AssetBase64' title: Audio required: - type - avatar_id - audio title: CreateAvatarRealtimeAudio type: object CreateAvatarRealtimeTextStream: additionalProperties: false description: >- Create a stream that accepts text deltas pushed over time via the ingest endpoint. Clients POST additional text deltas to /v3/avatar-realtime/{stream_id}/text as they become available (e.g. as an upstream LLM streams tokens). The session must be seeded with a non-empty initial `text` so the avatar has something to start speaking immediately — otherwise the emitter would idle out before any audio is produced. properties: type: const: text_stream description: 'Audio source type: streaming text-to-speech.' title: Type type: string avatar_id: description: HeyGen photo avatar or motion avatar look ID. title: Avatar Id type: string voice_id: description: Voice ID for text-to-speech. title: Voice Id type: string text: description: >- Initial text seed for the avatar to start speaking. Further text is appended via the ingest endpoint. minLength: 1 title: Text type: string required: - type - avatar_id - voice_id - text title: CreateAvatarRealtimeTextStream type: object CreateAvatarRealtimeTTS: additionalProperties: false description: Create a stream with text-to-speech audio. properties: type: const: tts description: 'Audio source type: text-to-speech.' title: Type type: string avatar_id: description: HeyGen photo avatar or motion avatar look ID. title: Avatar Id type: string text: description: Text script for the avatar to speak. minLength: 1 title: Text type: string voice_id: description: Voice ID for text-to-speech. title: Voice Id type: string required: - type - avatar_id - text - voice_id title: CreateAvatarRealtimeTTS type: object 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 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. ````