Send Message or Request Revision

Sends a follow-up message to an existing session. Use to answer agent questions, add context, or request edits to a generated video. Only valid for sessions created in chat mode.

POST /v3/video-agents/{session_id}

Send Message or Request Revision

cURL

curl --request POST \
  --url https://api.heygen.com/v3/video-agents/{session_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "message": "<string>",
  "avatar_id": "<string>",
  "voice_id": "<string>",
  "files": [
    {
      "type": "<string>",
      "url": "<string>"
    }
  ],
  "auto_proceed": false,
  "skip_agentic_stop": false
}
'

200

{
  "data": {
    "session_id": "<string>",
    "run_id": "<string>",
    "title": "<string>"
  }
}

Authorizations

ApiKeyAuthBearerAuth

x-api-key · string · header · required

HeyGen API key. Obtain from your HeyGen dashboard.

Path Parameters

session_id · string · required

Session ID

Body

application/json

Request body for sending a follow-up message, answering the agent's question, or requesting edits and revisions to a previously generated video.

message · string · required

Text message to the agent

Required string length: 1 - 10000

avatar_id · string | null

Override avatar for this message

voice_id · string | null

Override voice for this message

files · (AssetUrl · object | AssetId · object | AssetBase64 · object)[] | null

Optional file attachments (max 20 files)

Maximum array length: 20

Asset input via publicly accessible HTTPS URL.

AssetUrl

AssetId

AssetBase64

Show child attributes

auto_proceed · boolean · default: false

If true, skip interactive review and go straight to video generation (no storyboard approval step)

skip_agentic_stop · boolean · default: false

Set true to disable agentic stop (not recommended)

Response

200

application/json

Successful response

data · SendMessageResponse · object

Response from sending a message to a session.

Show child attributes