Edit Scenes

Revise two scenes of a Video Agent video without touching the rest. Read the scene list, send an edit_plan with one instruction per scene, and poll the new draft.

API reference: Get Video Scenes · Send Message or Request Revision · Get Video · List Session Videos

A scene edit changes only the scenes you name. Everything else in the video keeps its script, visuals, and pacing, so a small fix stays small: one call, a few minutes of rendering, and no re-prompting of the whole video. It works on any Video Agent session, whether you created it with "mode": "generate" or "mode": "chat" (see Interactive Sessions).

Before · the first cut, four scenes from one prompt.

After · one edit_plan call. Scene 2 became a night-time room, scene 4 dropped the pre-order line. Scenes 1 and 3 are unchanged.

Three calls

1. Read the scenes

   GET /v3/videos/{video_id}/scenes on a completed video from the session. The response lists every scene in order with its id, script, background, and elements, plus one edit_version for the whole document. Wait for the video to reach completed first: while it is still rendering this call returns 409 resource_not_ready.

2. Send the edit plan

   POST /v3/video-agents/{session_id} with an edit_plan array. Each item names one scene_id, the change in plain language, the scene_snapshot_video_id you read the scene from, and that snapshot’s edit_version. No message is needed. The response carries the video_id of the new working draft.

3. Poll the draft

   GET /v3/videos/{video_id} with the returned video_id until status is completed. The session’s own video_id stays null while the edit runs, so poll the draft directly. GET /v3/video-agents/{session_id}/videos lists every cut the session has produced.

Example

The plan below produced the “after” video above. Two items, two scenes, one request.

curl -X POST "https://api.heygen.com/v3/video-agents/$SESSION_ID" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "edit_plan": [
      {
        "scene_id": "ff943f68-159d-463b-84ac-b784a61c8bca",
        "text": "Change the on-screen headline to Evening mode and make the background a much darker, warmer night-time room with a single lit lamp. Keep the narration the same.",
        "scene_snapshot_video_id": "7c852479652e4e09b2cc6b12382b31f6",
        "edit_version": "e6eb1e63074cbfc694e4e6b64d3dc1b9cc004da54074d073631baaa825ce0e53"
      },
      {
        "scene_id": "e89c22a1-7619-4f26-bdb5-c5ec5555da4e",
        "text": "Replace the closing line with: Lumen. Light that knows you. Available now. Drop the pre-order URL from narration and on-screen text.",
        "scene_snapshot_video_id": "7c852479652e4e09b2cc6b12382b31f6",
        "edit_version": "e6eb1e63074cbfc694e4e6b64d3dc1b9cc004da54074d073631baaa825ce0e53"
      }
    ]
  }'

Response

{
  "data": {
    "session_id": "6cbd1fbc886b434a920acfed05fa931b",
    "run_id": "c3817fcd60b543da8480b6bc7d03026f",
    "title": "Lumen Explainer Video",
    "video_id": "1af65ebabfdc48ed84fc2f4ec2abd20f"
  }
}

With the CLI, the same turn is heygen video scenes get <video_id> followed by heygen video-agent send <session_id> -d edit_plan.json.

What to expect

Situation	What happens
Narration	Say “keep the narration” and the scene keeps its script while the visuals change. Give new copy and both change.
Untouched scenes	Same script and visuals as before. The new draft is a new document, so scene and element ids are reissued; compare by content, not by id.
Several edits in a row	Each accepted turn returns the current working draft in video_id. Read that draft’s scenes for the next edit_version.
edit_version no longer current	409 stale_edit_version. Read the scenes again and resend with the new version.
A scene_id outside the snapshot	400 invalid_parameter. The whole plan is rejected before anything is submitted, so a typo never produces a half-applied edit.
Reading scenes	A heavy read with a lower rate limit than GET /v3/videos/{video_id}. Poll the video for status and read scenes once it completes.
Plan size	Up to 50 items per request, each up to 10,000 characters. Items may point at different snapshots from the same session, including earlier videos.

Edit with an agent

Ask a coding agent to make the change for you: it reads the scenes, picks the ones that match your description, and sends the plan.

Prompt for your agent

Read https://developers.heygen.com/docs/edit-scenes.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. Video Agent session <SESSION_ID> has a completed video <VIDEO_ID>. Call GET /v3/videos/<VIDEO_ID>/scenes, show me each scene's script in one line, and ask me which scenes to change and how. Then send one POST /v3/video-agents/<SESSION_ID> with an edit_plan covering only those scenes, using the scene ids and edit_version you read. Poll the returned video_id until completed and give me the video URL.