Skip to main content

​
1. Get an API key

Sign up at lavendly.ai and create an API key from your dashboard. You’ll use it in the Authorization header on every request. 
export LAVENDLY_API_KEY=lv_live_…
export LAVENDLY_API=https://api.lavendly.ai

​
2. Render a video from a single prompt

The simplest possible call: a workflow with one shot, rendered server-side. 
WF=$(curl -s -X POST $LAVENDLY_API/v1/workflows \
  -H "Authorization: Bearer $LAVENDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bookshop fox",
    "shots": [
      { "prompt": "a sleepy fox in a bookshop discovering an old map",
        "duration": 5 }
    ]
  }' | jq -r .id)

JOB=$(curl -s -X POST $LAVENDLY_API/v1/workflows/$WF/renders \
  -H "Authorization: Bearer $LAVENDLY_API_KEY" -d '{}' | jq -r .job_id)

# Poll until done
while :; do
  STATUS=$(curl -s $LAVENDLY_API/v1/workflows/$WF/renders/$JOB \
    -H "Authorization: Bearer $LAVENDLY_API_KEY" | jq -r .status)
  echo "$STATUS"
  [[ $STATUS == "done" || $STATUS == "failed" ]] && break
  sleep 4
done

curl -s $LAVENDLY_API/v1/workflows/$WF/renders/$JOB \
  -H "Authorization: Bearer $LAVENDLY_API_KEY" | jq .result.video_url

​
3. Add a voiceover and a music bed

Once you have a workflow, attach extra tracks to a shot: 
# Voiceover with auto-generated captions
curl -X POST $LAVENDLY_API/v1/workflows/$WF/clips/shot_1/tracks \
  -H "Authorization: Bearer $LAVENDLY_API_KEY" \
  -H "Idempotency-Key: vo-$WF" \
  -d '{
    "kind": "voiceover",
    "script": "Once upon a time, in a quiet bookshop...",
    "subtitleStyle": "tiktok"
  }'

# Music bed with auto-ducking under the voiceover
curl -X POST $LAVENDLY_API/v1/workflows/$WF/clips/shot_1/tracks \
  -H "Authorization: Bearer $LAVENDLY_API_KEY" \
  -H "Idempotency-Key: music-$WF" \
  -d '{ "kind": "music", "mood": "warm cozy ambient", "ducking": true }'
Re-render and you get the finished, mixed clip with burn-in captions.

​
4. Give an agent the same capability

Anything you just did with cURL, an agent can do through the agent skills interface. The same operations are exposed as tools; the same idempotency keys keep retries safe. Try this prompt in any agent that’s been wired up to Lavendly:
Create a 5-second video of a fox in a bookshop, narrate it in a warm voice with captions, lay a cozy ambient track underneath, and send me the URL when it’s done.
That’s six tool calls and a render. No glue code on your side.

​
What’s next

Wire an agent in

Two-minute setup for Claude Desktop, Cursor, and other agent runtimes.

Node SDK

Cookbook patterns.

Python SDK

Cookbook patterns.

API reference

Every operation, response shape, and error code.