Skip to main content
POST
/
v1
/
workflows
/
{id}
/
clips
/
{clip_id}
/
tracks
curl -X POST https://api.lavendly.ai/v1/workflows/wf_xyz/clips/vid1/tracks \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $LAVENDLY_API_KEY' \
  -H 'Idempotency-Key: attach-vo-2026-05-16' \
  -d '{
    "kind":  "voiceover",
    "url":   "https://cdn.lavendly.ai/voice/abc.mp3",
    "text":  "Once upon a time...",
    "voice": "narrator"
  }'

{
  "track_id":       "tr_a1b2c3d4e5f6",
  "source_node_id": "voiceover_lq3z9m_8fa1c0",
  "target_clip_id": "vid1",
  "kind":           "voiceover",
  "url":            "https://cdn.lavendly.ai/voice/abc.mp3"
}
Creates a new audio source node (voiceover, music, or audioUpload) and wires an edge from it to the target clip. The next GET audio reflects the change.
​
id
string
required
Workflow id.
​
clip_id
string
required
Clip id.

​
Body

​
kind
string
required
voiceover or music.
​
url
string
required
Audio asset URL.
​
text
string
Original script (voiceover only).
​
voice
string
Voice id used for synthesis (voiceover only).
​
volume
number
default:"1"
0..2. Default 0.4 for music, 1 for voiceover.
​
muted
boolean
default:"false"
​
ducking
boolean
Drops music by ~8 dB during voiceover. Defaults to true for music tracks.

​
Idempotency

Send Idempotency-Key to make retries safe. Same key within 5 min returns the same track_id. 
curl -X POST https://api.lavendly.ai/v1/workflows/wf_xyz/clips/vid1/tracks \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $LAVENDLY_API_KEY' \
  -H 'Idempotency-Key: attach-vo-2026-05-16' \
  -d '{
    "kind":  "voiceover",
    "url":   "https://cdn.lavendly.ai/voice/abc.mp3",
    "text":  "Once upon a time...",
    "voice": "narrator"
  }'

{
  "track_id":       "tr_a1b2c3d4e5f6",
  "source_node_id": "voiceover_lq3z9m_8fa1c0",
  "target_clip_id": "vid1",
  "kind":           "voiceover",
  "url":            "https://cdn.lavendly.ai/voice/abc.mp3"
}