Synthesia API BETA - Quick Start Guide

❗️

Please note: Synthesia API is in BETA

Developing an important application? Synthesia API is currently in BETA and is not actively being improved. We currently don't provide any support for our API and do not guarantee any further active development.

1. 🆕 Prerequisite: Get a paid Synthesia STUDIO account

Create Synthesia STUDIO account

Synthesia STUDIO lets you create one-off videos and test different types of videos before automating the process through the API. Also, Synthesia STUDIO lets you define API templates with personalization variables that you can call later through the API.

You need to have a paid account to Synthesia STUDIO to start using our API. You can create free videos in the test mode of our API.

2. 🗝️ Create an API key

Create your API key

Once you’ve become a Synthesia STUDIO user, head to accounts settings, scroll down to "API Keys" area, and create a new API key.

3. 🎬 Create the first video

See Detailed API Reference

We will create the first video in “test” mode. Test videos are free and not counted towards your quota. If you create video in “test” mode, we will override your background with Synthesia branded background.

curl https://api.synthesia.io/v2/videos  \
  -H "Authorization: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{ "test": true, "input": [{ "scriptText": "Hello, World! This is my first synthetic video, made with the Synthesia API!", "avatar": "anna_costume1_cameraA", "background": "green_screen"}] }'

We will send you a response {...} where you can find an ID of the newly created video.

Create videos via templates: alternatively, you can create videos via templates as well. Read more about how to use templates here.

4. 📽️ Wait for your video

See Detailed API Reference

As soon as you create a video, we begin processing it. This can take from 3-10 minutes. When the video is ready for playback, the video status changes to COMPLETE.

You can poll the API to see the video status with the following call:

curl https://api.synthesia.io/v2/videos/${VIDEO_ID} \
  -H "Authorization: ${API_KEY}" \
  -X GET

Webhooks: rather than polling, it is possible to configure a webhook to which we will send a notification when a video completes successfully. For more information, refer to the webhook documentation.

5. 📂 Download the video

Once your video is ready, the response will include a time-limited “download link”.

See example video object response here.

You can use the link to download the video as .mp4.

curl ${DOWNLOAD_URL} --output my_first_synthetic_video.mp4

6. 📜 Explore our detailed API documentation

You can see our detailed API reference with all current possible calls and parameters here.