Build your first video

This guide walks through building a 5-second clip with a voiceover and a music bed, end-to-end through the API. The same flow takes about 30 seconds on the canvas, but seeing the API version makes the data model click.

export LAVENDLY_API_KEY=lv_…
export API=https://lavendly.ai/api
AUTH="Authorization: Bearer $LAVENDLY_API_KEY"

1. Create the workflow

WF=$(curl -s -X POST $API/v1/workflows \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{
    "name": "Bookshop fox",
    "shots": [
      { "prompt": "a sleepy fox in a bookshop discovering an old map",
        "duration": 6 }
    ]
  }' | jq -r .id)

# Clip ids are generated (they look like vid_1790000000000_0). Take the first.
CLIP=$(curl -s $API/v1/workflows/$WF -H "$AUTH" \
  | jq -r '.nodes[] | select(.type == "videoGenerator") | .id' | head -1)

2. Attach a voiceover with captions

curl -s -X POST $API/v1/workflows/$WF/clips/$CLIP/tracks \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: vo-$WF" \
  -d '{
    "kind":          "voiceover",
    "script":        "Some maps lead nowhere. This one led home.",
    "subtitleStyle": "tiktok"
  }'

The platform synthesizes the voiceover, transcribes it with word-level timing, and stores both the audio and the caption data on the workflow.

3. Attach a music bed with ducking

curl -s -X POST $API/v1/workflows/$WF/clips/$CLIP/tracks \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: music-$WF" \
  -d '{
    "kind":    "music",
    "mood":    "warm cozy acoustic",
    "volume":  0.4,
    "ducking": true
  }'

ducking: true drops the music ~8 dB whenever the voiceover speaks, so the narration stays on top.

4. Set the audio mix

We want the shot’s baked audio blended at 60% with the new tracks:

curl -s -X PATCH $API/v1/workflows/$WF/clips/$CLIP/audio \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{ "native_audio": { "mode": "mix", "volume": 0.6 } }'

5. Price it, render, and poll

The render generates the scene and the audio (that is what costs credits), then stitches them. Price it first and pass that price as max_credits, so it can never spend more:

PRICE=$(curl -s $API/v1/workflows/$WF/cost-estimate -H "$AUTH" | jq .remaining)

JOB=$(curl -s -X POST $API/v1/workflows/$WF/renders \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: render-$WF" -d "{\"max_credits\": $PRICE}" | jq -r .job_id)

while :; do
  S=$(curl -s $API/v1/workflows/$WF/renders/$JOB -H "$AUTH" | jq -r .status)
  echo "status=$S"
  [[ "$S" == "done" || "$S" == "failed" ]] && break
  sleep 4
done

curl -s $API/v1/workflows/$WF/renders/$JOB -H "$AUTH" | jq .result

Expected result:

{
  "video_url":     "https://lavendly.ai/api/v1/storage/m/…/video.mp4",
  "duration":      6,
  "quality_check": { "ok": true, "rubric": { "overall": 0.86 } }
}

The same flow, agent-driven

Once an agent has the Lavendly MCP and a skill loaded, all five steps above collapse into one prompt:

Make me a 5-second video: a sleepy fox in a bookshop discovering an old map. Narrate it warmly. Cozy acoustic bed underneath. Captions on. Send me the URL.

The agent runs the same calls in the same order, applies the same idempotency keys, and returns the URL. See the storyteller skill for the exact operating manual.

Welcome

Guides

MCP

Agent skills

SDKs

API reference

Build your first video

1. Create the workflow

2. Attach a voiceover with captions

3. Attach a music bed with ducking

4. Set the audio mix

5. Price it, render, and poll

The same flow, agent-driven

​1. Create the workflow

​2. Attach a voiceover with captions

​3. Attach a music bed with ducking

​4. Set the audio mix

​5. Price it, render, and poll

​The same flow, agent-driven

1. Create the workflow

2. Attach a voiceover with captions

3. Attach a music bed with ducking

4. Set the audio mix

5. Price it, render, and poll

The same flow, agent-driven