---
title: "Edit Custom Agent Video"
method: POST
path: "/v3/custom-agents/videos/{video_id}/edits"
tags: ["Custom Agents"]
---

# Edit Custom Agent Video

`POST /v3/custom-agents/videos/{video_id}/edits`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/custom-agents/videos/{video_id}/edits`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Edits a completed custom-agent video from a natural-language instruction, reusing the source run's composition and paid media. Returns a NEW `video_id`; poll GET /v3/custom-agents/videos/{video_id} for status and the MP4 URL.

## Path parameters

- `video_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- CustomAgentVideoEditRequest: Body for POST /v3/custom-agents/videos/{video_id}/edits. `video_id` (in the path) is the source video to edit; it is self-identifying, so the agent is resolved from its workflow type and no agent_id is needed. `user_input` is the natural-language edit instruction the agent applies to the source video's prior composition.
  - `user_input` string, required: What to change about the source video.

## Response `202`

Accepted — submission acknowledged; poll for completion.

- object
  - `data` CustomAgentVideoCreateResponse: 202 response body for POST /v3/custom-agents/{agent_id}/videos.
    - `video_id` string, required: Opaque id; poll GET /v3/custom-agents/videos/{video_id}.
    - `status` string: Initial workflow status.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `404`: Resource not found
- `409`: A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/custom-agents/videos/:video_id/edits/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)