Edit Video

Change a rendered video’s script, voice, or avatar style in one call. Only the scenes you name re-render and bill, and the video keeps its video_id.

API reference: Get Video Scenes · Get Video

POST /v3/videos/{video_id} edits a finished video in place. Name the scenes, script lines, and avatars to change by the ids GET /v3/videos/{video_id}/scenes returns, send only the fields that change, and HeyGen renders the same video_id again. Scenes you leave out keep their audio and avatar footage, so a one-line fix renders and bills one scene.

Before · a three-scene studio video from POST /v3/videos.

After · one edit call. Scene 1 has a new voice at 1.1× speed, scene 3 a new closing line. Scene 2 is the same footage.

Three calls

1. Read the scenes

   GET /v3/videos/{video_id}/scenes on a completed video. It returns one edit_version for the video, and every scene, element, and script line with its id. See Video Scenes for the shape.

2. Send the edit

   POST /v3/videos/{video_id} with the edit_version, the changes keyed by id, and a new UUID in the Idempotency-Key header. The response is 200 with status: "pending" and a version_id for the new render.

3. Poll the video

   GET /v3/videos/{video_id} until status is completed, or pass callback_url and callback_id in the edit body to get a webhook. Read the scenes again for the next edit_version before your next edit.

Example

The request below produced the “after” video above: a new voice on scene 1 and new text on scene 3.

curl -X POST "https://api.heygen.com/v3/videos/9202d2d1a928090f0f7f51a1c7e35c8a" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "edit_version": "3c3237d23c922866e925ec7e877e87f6ac606fb03288286a37b54ab96d818c00",
    "scenes": [
      {
        "id": "scene_0_1793648761146_ie0tymo0x",
        "script": [
          {
            "id": "script_0_1793648761145_iwbuwgrse",
            "type": "text",
            "voice_id": "80b17a1be1594e578b92c0ddf4a37fc8",
            "voice_settings": { "engine_settings": { "engine_type": "starfish" }, "speed": 1.1 }
          }
        ]
      },
      {
        "id": "scene_2_1793648761146_o4iqp9ht0",
        "script": [
          {
            "id": "script_2_1793648761146_hyqywuoj9",
            "type": "text",
            "text": "Thanks for watching. Questions go to the finance channel."
          }
        ]
      }
    ]
  }'

Response

{
  "data": {
    "video_id": "9202d2d1a928090f0f7f51a1c7e35c8a",
    "status": "pending",
    "version_id": "f1fc7f8bcc984cf1bc9dfcacc0841ee2"
  }
}

What you can edit

Edit	Fields	Rules
Script text	scenes[].script[].text	Up to 5,000 characters per line, with the same pause tags create accepts. The line keeps its voice and the voice’s language.
Voice	scenes[].script[].voice_id with voice_settings	A voice changes per scene: set the same voice_id and voice_settings on every text line in the scene. voice_settings.engine_settings is required. speed (0.5–1.5), volume (0.0–1.0), and locale are optional.
Avatar style	scenes[].elements[] with type: "avatar": engine, expressiveness, motion_prompt	One engine for the whole video, so switch every avatar in one request. engine moves between avatar_iv and avatar_v. motion_prompt applies on Avatar V and to photo avatars on Avatar IV. expressiveness applies to photo avatars on Avatar IV. On any other avatar, either field answers 400 invalid_parameter.

Each line and element entry carries its id and its type, as the scenes read shows them. Omitted fields keep their value. To empty motion_prompt or expressiveness, name it in the entry’s clear list. One request edits up to 10 scenes, so an engine switch covers videos with up to 10 avatar scenes.

Avatar style edits cover scenes with one avatar, in videos whose avatars are all photo avatars or all video avatars. Read-back fields outside the table, such as avatar_id, background, source, and actions, answer 400 edit_not_supported with param naming the field. Any other key answers 400 invalid_parameter.

Script text

{
  "edit_version": "<from GET scenes>",
  "scenes": [
    {
      "id": "<scene id>",
      "script": [{ "id": "<line id>", "type": "text", "text": "Revenue grew fifteen percent this quarter." }]
    }
  ]
}

An engine switch keeps each scene’s audio, so the video’s length stays the same. An edited scene renders as it would if you had created the video with those values through POST /v3/videos.

Retries and versions

Situation	Response
Same Idempotency-Key, same body, within 24 hours	The first response again, with the same version_id. One render, one charge.
Same Idempotency-Key, different body	409 conflict. Use a new key for a new edit.
Another edit while the video renders	409 resource_not_ready. Wait for completed.
An edit_version from before the last render	409 stale_edit_version. Read the scenes again and resend with the new version.
A body with only edit_version	Renders the video again unchanged. Scenes served from the avatar cache are free.
500 internal_error	The render may have started. Retry with the same key and the same body.
503 render_not_started	The edit is saved and its render did not start. Read the scenes for the new edit_version, then send only that edit_version with a new key.
Any 4xx	Nothing is saved. Scenes, edit_version, and status stay as they were.

Billing

An edit bills as an API render of the scenes it changes, at the rate of each scene’s engine. A scene drops out of the charge when every avatar in it is served from the avatar cache, which is typically the case for scenes you leave out. Scenes without an avatar bill on every render. For a three-scene video:

Request	Scenes typically billed
New text on one line	1
New voice on scene 1, new text on scene 3	2
Every avatar from avatar_iv to avatar_v	3, with audio reused
Only edit_version	0

Errors

Errors use the v3 envelope: code, message, and param, which names the field by its position in your request, for example scenes.0.script.0.text.

Status	code	Cause
400	invalid_parameter	An unknown key or id, a line or element under the wrong scene, a value out of range, text over 5,000 characters, a missing or malformed Idempotency-Key
400	edit_not_supported	A read-back field outside the table above, avatars on different engines, two avatars in one scene, Avatar III, expressive or masked avatars, more_blinking
400	scenes_unavailable	The video predates the current editor format
400	avatar_consent_required	An avatar in the video needs consent before it can render
400	video_not_editable	A Video Agent video (edit it with Edit Scenes), an interactive video, or avatars and voices the workspace can no longer use
402	insufficient_credit	Not enough credits for the changed scenes
403	ai_vendor_access_restricted	The workspace’s policy blocks the requested voice engine
404	video_not_found	No such video in your workspace
409	resource_not_ready	The video is rendering
409	stale_edit_version	The video changed after you read the scenes
409	conflict	The Idempotency-Key was used with a different body
409	request_in_progress	The same key is still being processed
429	rate_limit_exceeded	Too many requests. Retry after Retry-After seconds.
500	internal_error	The render may have started. Retry with the same key and the same body.
503	service_unavailable	The edit could not be applied in time. Nothing is saved; retry.
503	render_not_started	The edit is saved and its render did not start. Read the scenes again and send only the new edit_version, with a new key.

Edit with an agent

Prompt for your agent

Read https://developers.heygen.com/edit-video.md and https://developers.heygen.com/docs/for-ai-agents.md first. My HeyGen API key is in the HEYGEN_API_KEY environment variable; never ask me to paste it. Call GET /v3/videos/<VIDEO_ID>/scenes and show me each scene's script in one line. Ask me what to change. Then send one POST /v3/videos/<VIDEO_ID> with the edit_version you read, only the lines and avatars that change, and a new UUID as the Idempotency-Key. Poll GET /v3/videos/<VIDEO_ID> until completed and give me the video URL.