HEheygen
Podcasts

Create Podcast

Changed on

Generate a multi-avatar conversational podcast video from a topic and/or source files plus two avatars. Generation is asynchronous — use the returned podcast_id to poll status via GET /v3/podcasts/{podcast_id}.

post/v3/podcasts

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v3/podcasts
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Headers

Idempotency-Keystring

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Request body

topicstring nullable

Free-text topic / angle / instructions for the conversation. Provide topic, source_files, or both.

host_avatar_idstring required

Avatar id for the host.

guest_avatar_idstring required

Avatar id for the guest.

host_voice_idstring required

Voice id for the host. List voices via GET /v3/voices.

guest_voice_idstring required

Voice id for the guest. List voices via GET /v3/voices.

layout'landscape' | 'portrait'

Output aspect ratio: 'landscape' (16:9) or 'portrait' (9:16).

duration'auto' | '1min' | '2min' | '3min' | '5min'

Target spoken length. 'auto' lets the generator pick the length.

instructionsstring nullable

Free-form scene/studio instructions (e.g. setting, tone). Used verbatim to describe the studio when set.

callback_urlstring nullable

Optional webhook URL. When set, HeyGen POSTs a notification here when the podcast reaches a terminal state (completed or failed), so you don't have to poll GET /v3/podcasts/{podcast_id}.

callback_idstring nullable

Caller-defined identifier echoed back in the webhook payload so you can correlate the callback with this request.

Response

Accepted — submission acknowledged; poll for completion.

Changes