Attach track

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"
}

POST

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.

string

required

Workflow id.

string

required

Clip id.

Body

string

required

voiceover or music.

string

required

Audio asset URL.

string

Original script (voiceover only).

string

Voice id used for synthesis (voiceover only).

number

default:"1"

0..2. Default 0.4 for music, 1 for voiceover.

boolean

default:"false"

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"
}

Welcome

Guides

MCP

Agent skills

SDKs

API reference

Body

Idempotency

​Body

​Idempotency

Body

Idempotency