Quickstart

Create a demo video with one request, then fetch the finished video.

1. Get an API key

   Open the Developers page in the app and select Create key. Only owners and admins of a paid plan can create keys. The key starts with dsk_live_ and is shown once, so store it somewhere safe.

   export DEMOSMITH_API_KEY="dsk_live_..."
   
2. Create a demo

   Send the site’s URL and what the demo should show. The request returns at once.

   curl

   curl https://platform.demosmith.ai/v1/demos \
     -H "Authorization: Bearer $DEMOSMITH_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://cal.com",
       "task": "Show how to book a 30-minute meeting from a public booking page"
     }'
   

   Response (201)

   {
     "id": "5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34",
     "object": "demo",
     "status": "queued",
     "progress": { "percent": 0, "eta_seconds": 900 },
     "check_again_in_seconds": 15,
     "app_url": "https://app.demosmith.ai/demos/5b9e3c7a-2f41-4c8e-9a51-7d0b6e2f1c34"
   }
   

   Add an idempotency_key to the request. If your request times out and you send it again with the same key, you get the same demo back instead of a second one.

3. Wait for the video

   A demo takes about 5 to 20 minutes. Either register a webhook and get demo.completed, or poll the demo, waiting check_again_in_seconds between requests.

   Python

   import time
   
   while demo["status"] not in ("completed", "failed", "canceled"):
       time.sleep(demo["check_again_in_seconds"])
       demo = requests.get(
           f"https://platform.demosmith.ai/v1/demos/{demo['id']}",
           headers={"Authorization": f"Bearer {os.environ['DEMOSMITH_API_KEY']}"},
       ).json()
       if demo["status"] == "input_required":
           print("The agent needs an answer:", demo["input_request"]["answer_url"])
   

   If the agent reaches a sign-in page, the demo pauses with status: "input_required". See When the agent needs an answer.

4. Get the video

   When status is completed, the demo has a video object.

   "video": {
     "url": "https://...",
     "download_url": "https://...",
     "expires_at": "2026-11-07T14:12:00Z",
     "duration_seconds": 63.4
   }
   

   url plays in a browser and download_url downloads the MP4. Both expire after 2 hours; fetch the demo again for fresh links. The demo also stays in your library in the app (app_url).

​

Next steps

Choose language, voice and more

options sets the language, voice, tone, subtitles, music and resolution.

Webhooks

Stop polling and get each step as it happens.