Video Agent

Send Video Agent Message

Sends a follow-up turn to a session created in either generate or chat mode; follow-up turns preserve the session mode. Send a message, a scene edit_plan built from GET /v3/videos//scenes, or both. Items may reference different scene snapshots from this session; none identifies the output draft. edit_version is not a document lock, so two edits from one version may both be accepted. Returns the current working draft in video_id. Poll GET /v3/videos/ for status.

POST

video-agents

{session_id}

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": "",
  "avatar_id": "<string>",
  "voice_id": "<string>",
  "brand_kit_id": "<string>",
  "files": [
    {
      "type": "url",
      "url": "<string>"
    }
  ],
  "edit_plan": [
    {
      "scene_id": "<string>",
      "text": "<string>",
      "scene_snapshot_video_id": "<string>",
      "edit_version": "<string>"
    }
  ]
}
'

import requests

url = "https://api.heygen.com/v3/video-agents/{session_id}"

payload = {
    "message": "",
    "avatar_id": "<string>",
    "voice_id": "<string>",
    "brand_kit_id": "<string>",
    "files": [
        {
            "type": "url",
            "url": "<string>"
        }
    ],
    "edit_plan": [
        {
            "scene_id": "<string>",
            "text": "<string>",
            "scene_snapshot_video_id": "<string>",
            "edit_version": "<string>"
        }
    ]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: '',
    avatar_id: '<string>',
    voice_id: '<string>',
    brand_kit_id: '<string>',
    files: [{type: 'url', url: '<string>'}],
    edit_plan: [
      {
        scene_id: '<string>',
        text: '<string>',
        scene_snapshot_video_id: '<string>',
        edit_version: '<string>'
      }
    ]
  })
};

fetch('https://api.heygen.com/v3/video-agents/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/video-agents/{session_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'message' => '',
    'avatar_id' => '<string>',
    'voice_id' => '<string>',
    'brand_kit_id' => '<string>',
    'files' => [
        [
                'type' => 'url',
                'url' => '<string>'
        ]
    ],
    'edit_plan' => [
        [
                'scene_id' => '<string>',
                'text' => '<string>',
                'scene_snapshot_video_id' => '<string>',
                'edit_version' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heygen.com/v3/video-agents/{session_id}"

	payload := strings.NewReader("{\n  \"message\": \"\",\n  \"avatar_id\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"brand_kit_id\": \"<string>\",\n  \"files\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"edit_plan\": [\n    {\n      \"scene_id\": \"<string>\",\n      \"text\": \"<string>\",\n      \"scene_snapshot_video_id\": \"<string>\",\n      \"edit_version\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.heygen.com/v3/video-agents/{session_id}")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"\",\n  \"avatar_id\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"brand_kit_id\": \"<string>\",\n  \"files\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"edit_plan\": [\n    {\n      \"scene_id\": \"<string>\",\n      \"text\": \"<string>\",\n      \"scene_snapshot_video_id\": \"<string>\",\n      \"edit_version\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/video-agents/{session_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"message\": \"\",\n  \"avatar_id\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"brand_kit_id\": \"<string>\",\n  \"files\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"edit_plan\": [\n    {\n      \"scene_id\": \"<string>\",\n      \"text\": \"<string>\",\n      \"scene_snapshot_video_id\": \"<string>\",\n      \"edit_version\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

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

Authorizations

x-api-key

string

header

required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

Idempotency-Key

string

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.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Path Parameters

session_id

string

required

Session ID

Body

application/json

SendMessageRequest
SendMessageRequest

One conversational or scene-edit turn in an existing Video Agent session.

message

string

default:""

required

Text message to the agent. Required when edit_plan is omitted; may be omitted or empty when edit_plan is provided.

Required string length: 1 - 10000

avatar_id

string | null

Override avatar for this message

voice_id

string | null

Override voice for this message

brand_kit_id

string | null

Brand kit ID to apply for this message. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted.

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

edit_plan

VideoAgentSceneEdit · object[] | null

Scene-scoped natural-language edits to validate and submit atomically. Required when message is omitted or empty.

Required array length: 1 - 50 elements

Show child attributes

Response

Successful response

data

SendMessageResponse · object

Response from submitting a turn to a session.

Show child attributes

⌘I

Send Video Agent Message

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": "",
  "avatar_id": "<string>",
  "voice_id": "<string>",
  "brand_kit_id": "<string>",
  "files": [
    {
      "type": "url",
      "url": "<string>"
    }
  ],
  "edit_plan": [
    {
      "scene_id": "<string>",
      "text": "<string>",
      "scene_snapshot_video_id": "<string>",
      "edit_version": "<string>"
    }
  ]
}
'

import requests

url = "https://api.heygen.com/v3/video-agents/{session_id}"

payload = {
    "message": "",
    "avatar_id": "<string>",
    "voice_id": "<string>",
    "brand_kit_id": "<string>",
    "files": [
        {
            "type": "url",
            "url": "<string>"
        }
    ],
    "edit_plan": [
        {
            "scene_id": "<string>",
            "text": "<string>",
            "scene_snapshot_video_id": "<string>",
            "edit_version": "<string>"
        }
    ]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: '',
    avatar_id: '<string>',
    voice_id: '<string>',
    brand_kit_id: '<string>',
    files: [{type: 'url', url: '<string>'}],
    edit_plan: [
      {
        scene_id: '<string>',
        text: '<string>',
        scene_snapshot_video_id: '<string>',
        edit_version: '<string>'
      }
    ]
  })
};

fetch('https://api.heygen.com/v3/video-agents/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/video-agents/{session_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'message' => '',
    'avatar_id' => '<string>',
    'voice_id' => '<string>',
    'brand_kit_id' => '<string>',
    'files' => [
        [
                'type' => 'url',
                'url' => '<string>'
        ]
    ],
    'edit_plan' => [
        [
                'scene_id' => '<string>',
                'text' => '<string>',
                'scene_snapshot_video_id' => '<string>',
                'edit_version' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heygen.com/v3/video-agents/{session_id}"

	payload := strings.NewReader("{\n  \"message\": \"\",\n  \"avatar_id\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"brand_kit_id\": \"<string>\",\n  \"files\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"edit_plan\": [\n    {\n      \"scene_id\": \"<string>\",\n      \"text\": \"<string>\",\n      \"scene_snapshot_video_id\": \"<string>\",\n      \"edit_version\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.heygen.com/v3/video-agents/{session_id}")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"\",\n  \"avatar_id\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"brand_kit_id\": \"<string>\",\n  \"files\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"edit_plan\": [\n    {\n      \"scene_id\": \"<string>\",\n      \"text\": \"<string>\",\n      \"scene_snapshot_video_id\": \"<string>\",\n      \"edit_version\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/video-agents/{session_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"message\": \"\",\n  \"avatar_id\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"brand_kit_id\": \"<string>\",\n  \"files\": [\n    {\n      \"type\": \"url\",\n      \"url\": \"<string>\"\n    }\n  ],\n  \"edit_plan\": [\n    {\n      \"scene_id\": \"<string>\",\n      \"text\": \"<string>\",\n      \"scene_snapshot_video_id\": \"<string>\",\n      \"edit_version\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

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

Video Agent

Brand

Avatars

Audio

Voices

Models

Videos

Templates

Video Translate

Lipsync

HyperFrames

User

API Keys

Webhooks

Folders

Assets

AI Clipping

Filler Word Removal

Batches

Video Translation Batches

Lipsync Batches

Asset Batches

Send Video Agent Message

Authorizations

Headers

Path Parameters

Body

Response