> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lavendly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach track

> Attach a voiceover or music track to a clip. Materializes a real canvas node.

Creates a new audio source node (`voiceover`, `music`, or `audioUpload`)
and wires an edge from it to the target clip. The next
[GET audio](/api-reference/audio/get-audio) reflects the change.

<ParamField path="id" type="string" required>Workflow id.</ParamField>
<ParamField path="clip_id" type="string" required>Clip id.</ParamField>

### Body

<ParamField body="kind" type="string" required>`voiceover` or `music`.</ParamField>
<ParamField body="url" type="string" required>Audio asset URL.</ParamField>
<ParamField body="text" type="string">Original script (voiceover only).</ParamField>
<ParamField body="voice" type="string">Voice id used for synthesis (voiceover only).</ParamField>
<ParamField body="volume" type="number" default="1">`0..2`. Default 0.4 for music, 1 for voiceover.</ParamField>

<ParamField body="muted" type="boolean" default="false" />

<ParamField body="ducking" type="boolean">Drops music by \~8 dB during voiceover. Defaults to `true` for music tracks.</ParamField>

### Idempotency

Send `Idempotency-Key` to make retries safe. Same key within 5 min returns
the same `track_id`.

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "track_id":       "tr_a1b2c3d4e5f6",
    "source_node_id": "voiceover_lq3z9m_8fa1c0",
    "target_clip_id": "vid1",
    "kind":           "voiceover",
    "url":            "https://cdn.lavendly.ai/voice/abc.mp3"
  }
  ```
</ResponseExample>