Skip to main content

​
Create Overdub

  • Endpoint: POST https://api.heygen.com/v3/overdubs
  • Purpose: Dub or replace audio on a video using a provided audio file. HeyGen re-syncs the speaker’s lip movements to match the new audio. The job runs asynchronously — poll status via the Get Overdub Details endpoint.

​
Authentication

HeaderValue
X-Api-KeyYour HeyGen API key
AuthorizationBearer YOUR_ACCESS_TOKEN (OAuth)

​
Quick Example

curl -X POST "https://api.heygen.com/v3/overdubs" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": { "type": "url", "url": "https://example.com/source.mp4" },
    "audio": { "type": "url", "url": "https://example.com/new-audio.mp3" }
  }'

​
Request Body

ParameterTypeRequiredDefaultDescription
videoobjectYes—Source video. Provide as { "type": "url", "url": "https://..." } or { "type": "asset_id", "asset_id": "..." } (from POST /v3/assets).
audioobjectYes—Replacement audio. Same format options as video.
titlestringNo—Display title for the overdub in the HeyGen dashboard.
modestringNo"speed"Quality mode: "speed" (faster) or "precision" (higher quality, uses avatar inference).
enable_captionbooleanNofalseGenerate captions for the output video.
enable_dynamic_durationbooleanNotrueAllow output duration to adjust to match the new audio length.
disable_music_trackbooleanNofalseStrip background music from the source video.
enable_speech_enhancementbooleanNofalseEnhance speech quality in the output.
enable_watermarkbooleanNofalseAdd a watermark to the output.
start_timenumberNo—Start time in seconds for partial overdub.
end_timenumberNo—End time in seconds for partial overdub.
keep_the_same_formatbooleanNo—Preserve the source video’s resolution and bitrate.
fps_modestringNo—Frame rate mode: "vfr", "cfr", or "passthrough".
callback_urlstringNo—Webhook URL — receives a POST when the job completes or fails.
callback_idstringNo—Arbitrary ID echoed back in the webhook payload.
folder_idstringNo—Organize the overdub into a specific project folder.

​
Response

{
  "data": {
    "overdub_id": "od_abc123"
  }
}
FieldTypeDescription
overdub_idstringUnique identifier. Use with GET /v3/overdubs/{overdub_id} to poll status.

​
Get Overdub Details

  • Endpoint: GET https://api.heygen.com/v3/overdubs/{overdub_id}
  • Purpose: Get detailed information about an overdub including status, download URL, and metadata.

​
Quick Example

curl -X GET "https://api.heygen.com/v3/overdubs/od_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

​
Path Parameters

ParameterTypeRequiredDescription
overdub_idstringYesUnique overdub identifier.

​
Response

{
  "data": {
    "id": "od_abc123",
    "title": "My Overdub",
    "status": "completed",
    "duration": 42.5,
    "video_url": "https://files.heygen.ai/...",
    "callback_id": null,
    "created_at": 1717000000,
    "failure_message": null
  }
}

​
Response Fields

FieldTypeDescription
idstringUnique overdub identifier.
titlestring or nullDisplay title.
statusstringCurrent status: "pending", "running", "completed", or "failed".
durationnumber or nullVideo duration in seconds. Present when completed.
video_urlstring or nullPresigned download URL for the output video. Only present when status is "completed".
callback_idstring or nullClient-provided callback ID.
created_atinteger or nullUnix timestamp of creation.
failure_messagestring or nullError description. Only present when status is "failed".

​
List Overdubs

  • Endpoint: GET https://api.heygen.com/v3/overdubs
  • Purpose: List overdubs with cursor-based pagination.

​
Quick Example

curl -X GET "https://api.heygen.com/v3/overdubs?limit=10" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

​
Query Parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo10Results per page (1–100).
tokenstringNo—Opaque cursor token for the next page.

​
Response

{
  "data": [
    {
      "id": "od_abc123",
      "title": "My Overdub",
      "status": "completed",
      "duration": 42.5,
      "video_url": "https://files.heygen.ai/...",
      "created_at": 1717000000
    }
  ],
  "has_more": false,
  "next_token": null
}

​
Update Overdub

  • Endpoint: PATCH https://api.heygen.com/v3/overdubs/{overdub_id}
  • Purpose: Update an overdub’s title.

​
Quick Example

curl -X PATCH "https://api.heygen.com/v3/overdubs/od_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Title" }'

​
Request Body

ParameterTypeRequiredDescription
titlestringYesNew title for the overdub.

​
Delete Overdub

  • Endpoint: DELETE https://api.heygen.com/v3/overdubs/{overdub_id}
  • Purpose: Permanently delete an overdub.

​
Quick Example

curl -X DELETE "https://api.heygen.com/v3/overdubs/od_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

​
Response

{
  "data": {
    "id": "od_abc123"
  }
}

​
Polling Pattern

Overdubs are processed asynchronously. After creating one, poll the Get Overdub Details endpoint until the status reaches "completed" or "failed". Status transitions: pending → running → completed | failed 
# Poll every 10 seconds
while true; do
  STATUS=$(curl -s "https://api.heygen.com/v3/overdubs/od_abc123" \
    -H "X-Api-Key: $HEYGEN_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 10
done

​
Asset Inputs

Both video and audio fields accept two input formats: By URL — any publicly accessible HTTPS link: 
{ "type": "url", "url": "https://example.com/file.mp4" }
By asset ID — reference a file previously uploaded via POST /v3/assets: 
{ "type": "asset_id", "asset_id": "asset_xyz789" }
Upload assets when your files aren’t publicly hosted or you want to reuse them across multiple API calls. See Assets for details.

​
Speed vs Precision

ModeSpeedQualityHow it works
"speed"FasterGoodAudio-only resync
"precision"SlowerHigherUses avatar inference for more accurate lip movements
Choose "precision" when the speaker’s face is prominent and lip-sync accuracy matters. Use "speed" for batch jobs or when turnaround time is the priority.