Haygen

Research/01-heygen-sdk-api.md

HeyGen SDK API Reference Notes

Key findings from reading @heygen/streaming-avatar v2.1.0 type definitions. Source: node_modules/@heygen/streaming-avatar/lib/index.d.ts

StreamingAvatar Class

constructor({ token, basePath }: StreamingAvatarApiConfig)
createStartAvatar(requestData: StartAvatarRequest): Promise<StartAvatarResponse>
speak(requestData: SpeakRequest): Promise<any>
startVoiceChat({ isInputAudioMuted }?: { isInputAudioMuted?: boolean }): Promise<void>
closeVoiceChat(): Promise<void>
on(eventType: string, listener: EventHandler): this
off(eventType: string, listener: EventHandler): this
interrupt(): Promise<any>
stopAvatar(): Promise<any>
keepAlive(): Promise<any>
muteInputAudio(): void
unmuteInputAudio(): void
pushToTalkStart(): Promise<void>
pushToTalkStop(): Promise<void>

StartAvatarRequest

{
  avatarName: string
  quality?: AvatarQuality  // Low | Medium | High
  language?: string        // default 'en'
  knowledgeBase?: string   // system prompt string (full text, not an ID)
  knowledgeId?: string     // pre-created HeyGen KB ID (V2 enhancement)
}

SpeakRequest

{
  text: string
  taskType?: TaskType   // REPEAT | TALK
  taskMode?: TaskMode
}

StreamingEvents Enum (key events)

Event	Fires when	Payload
`STREAM_READY`	WebRTC stream is ready	`MediaStream`
`STREAM_DISCONNECTED`	Session ends or connection drops	—
`AVATAR_START_TALKING`	Avatar begins speaking	—
`AVATAR_STOP_TALKING`	Avatar finishes speaking	—
`AVATAR_TALKING_MESSAGE`	Avatar speech text chunk	`{ message: string }`
`USER_TALKING_MESSAGE`	User speech text chunk (ASR)	`{ message: string }`
`USER_END_MESSAGE`	User stops speaking	`{ type: string, task_id: string }` — NO message field

Critical Finding: USER_END_MESSAGE

UserTalkingEndEvent definition:

interface UserTalkingEndEvent {
  type: string
  task_id: string
}

There is NO message field. Lite mode must accumulate from USER_TALKING_MESSAGE and drain on USER_END_MESSAGE. See ADR-003.

Package Quirk: CJS/ESM Conflict

@heygen/streaming-avatar declares "type": "module" but "main" points to a CJS file. In vitest, must use server.deps.inline. See ADR-004.

HeyGen REST API (Token Endpoint)

POST https://api.heygen.com/v1/streaming/create_token
Headers: X-Api-Key: {HEYGEN_API_KEY}
Response: { data: { token: string } }

Token is short-lived. Must be fetched server-side per session.

Knowledge Base API (V2 reference)

POST /v1/streaming/knowledge_base        — create
GET  /v1/streaming/knowledge_base/{id}   — retrieve
DELETE /v1/streaming/knowledge_base/{id} — delete

Not used in MVP. For large reusable corpora in V2.

Credits

Full mode: 1 credit = 30 seconds streaming
Lite mode: 1 credit = 1 minute streaming