API Reference

Express Avatars Overview 📙
D-ID Express Avatars provides a fast, scalable solution to transform your video footage into dynamic, reusable digital people. With Express Avatars, you can build a library of custom avatars in D-ID’s Studio, offering flexibility across multiple projects.

✴️ Introduction

D-ID offers two distinct methods for creating an Express Avatar: the Basic and Advanced API usage flows.

For users who want a quick and easy way to create videos, the Basic flow is the perfect choice. It simplifies the process by managing all the complex tasks—like handling consent scripts and uploading videos—directly within the D-ID Studio interface. Once these initial steps are done, the API takes over to generate videos effortlessly.

For more experienced developers looking for greater control and customization, the Advanced flow offers the flexibility to manage both avatar creation and video generation entirely through the API. This method requires the use of external hosting services but allows for seamless integration of the entire process into your application.

✴️ API Usage - Basic

The Basic flow is designed for users who want to create videos quickly without the need for custom integrations. In this process, all the complex tasks, such as handling consent scripts and video uploads, are managed directly through the D-ID Studio interface. Once these steps are completed, video creation continues through the API, just like with D-ID's other video creation endpoints.


➤✴️ Prerequisites

  1. Login to the D-ID Creative Studio
  2. Go to the Avatars Screen
  3. Click on Create Avatar, and select Express Avatar
  4. Follow the steps and guidelines presented on the screen.

Once the Express Avatar is ready, you can continue to the next step.


➤✴️ Video Creation

1. Fetch the Express Avatar

Fetch the created Express Avatar's status and properties.
To make the avatar speak with a cloned voice, save the voice_id for the next step.

GET https://api.d-id.com/scenes/avatars/{id} | Get a specific Express Avatar

{
    "object": "scene_avatar",
    "owner_id": "userID",
    "id": "avt_abcd123",
    "status": "done",
    "created_at": "2024-10-08T15:00:41.115Z",
    "created_by": "userID",
    "modified_at": "2024-10-08T15:07:15.811Z",
    "started_at": "2024-10-08T15:03:26.047",
    "completed_at": "2024-10-08T15:07:13.172",
    "name": "Alex",
    "thumbnail_url": "https://scenes-avatars.d-id.com/userID/avt_abcd123/thumbnail.png",
    "talking_preview_url": "https://scenes-avatars.d-id.com/userID/avt_abcd123/talking-preview.mp4",
    "image_url": "https://scenes-avatars.d-id.com/userID/avt_abcd123/image.png",
    "voice_id": "IfhpAQ4yN4MQ9ykyw3iK",
    "source_url": "https://scenes-avatars.d-id.com/userID/avt_abcd123/video.mp4",
    "persist": true,
    "preview_url": ""
}

To see all of the created Express Avatars, use the Get Express Avatars endpoint.

📘

Note

You can proceed only when the Avatar's status is "status": "done"


2. Create a Scene with your Express Avatar

Use the id (from the previous step) and place it in the avatar_id property.
To use the cloned voice created automatically in the creation process, make sure to include the voice_id fetched from the previous step.

POST https://api.d-id.com/scenes | Create a Scene

{
    "avatar_id": "avt_abcd123",
    "script": {
        "type": "text",
        "input": "This is what the avatar will say!",
        "provider": {
            "type": "elevenlabs",
            "voice_id": "VOICE_ID_FROM_GET_AVATAR_ID"
        }
    },
    "webhook": "webhook.site/alex_avatarcreation_result"
}

{
    "object": "scene",
    "id": "scn_xyz1234",
    "created_at": "2024-10-10T13:37:01.991Z",
    "status": "created"
}

👍

Use Webhooks!

Create an endpoint that accepts POST requests, and add it to the webhook field.
This endpoint will be triggered once the video is ready.


3. Get the Scene Video

GET https://api.d-id.com/scenes/{id} | Get a specific Scene

{
    "owner_id": "userID",
    "id": "scn_xyz12345",
    "created_at": "2024-10-10T13:37:01.991Z",
    "modified_at": "2024-10-10T13:37:34.805Z",
    "created_by": "userID",
    "avatar_id": "avt_abcd1234",
    "status": "started",
    "audio_url": "s3://d-id-scenes-prod/userID/scn_xyz12345/elevenlabs.wav",
    "pending_url": "s3://d-id-scenes-prod/userID/scn_xyz12345E/result.mp4",
    "started_at": "2024-10-10T13:37:02.079",
    "completed_at": "2024-10-10T13:37:34.671",
    "thumbnail_url": "s3://d-id-scenes-avatars-persistent-prod/userID/avt_abcd1234/thumbnail.png"
}

📘

Note

The output video will be located in the result_url field only when "status": "done"


✴️ API Usage - Advanced

The Advanced flow is designed for experienced developers who aim to manage the entire Express Avatar creation process and video generation through the API. This approach requires using external hosting services and offers the flexibility to integrate both avatar creation and video generation seamlessly into their applications.

➤✴️ Consent

To prevent technology misuse, we need to confirm the identity of the person in the video by reading a consent statement and dynamic passcode.

1. Create a Consent

POST https://api.d-id.com/consents | Create a Consent 

{
  "language": "english"
}

{
  "id": "cst_CgeFQXJD2PHelloMINPQHnY",
  "text": "I, [user name] confirm that I have all the necessary rights or consents to use this footage and voice recording for creating an Avatar from my 'User Submission' all in accordance with the Terms of Use. This is my dynamic passcode lake, grass, salad",
  "created_at": "2024-09-20T12:30:00.112Z",
  "created_by": "userID"
}

📘

Supported Consent Languages:

Dutch, Turkish, Swedish, Indonesian, Filipino, Czech, Romanian, Danish, Malay, Slovak, Croatian, English, Polish, German, Spanish, French, Italian and Portuguese

❗️

Expiration Period

The consent challenge will expire in 10 minutes after it is created - make sure to use it within that time!

The response id will be referred to as consent_id in the next steps.


2. Record a Video with the Consent Script

Record a video of your avatar subject reading aloud the text from the previous step's response and upload it to an external hosting service (e.g. Amazon S3).

👍

Consent Footage Tips:

  • Replace the [user name] with your Express Avatar's name
  • Pronounce only the provided consent script and nothing else, when recording the consent video
  • Only one person should be in the frame of the video
  • Ensure the speaker is facing the camera with their face visible at all times

3. Upload the Consent Video

POST https://api.d-id.com/consents/{id} | Upload a Consent Video

{
  "name": "Alex",
  "source_url": "https://yourwebsite.storage.com/AlexConsentFile.mp4",
  "webhook": "webhook.site/alex_verification_result"
}

Webhook will be fired once the consent is verified with "status":"done"
  • Include the URL of the recorded Consent video in the source_url field.
  • The Express Avatar's name must match the "[user name]" pronounced in the recorded Consent video.

👍

Use Webhooks!

Create an endpoint that accepts POST requests, and add it to the webhook field.
This endpoint will be triggered once the Consent video is verified.

📘

Note

You can proceed with the consent only when its "status": "done"

➤✴️ Express Avatar Creation

1. Record a video with your Avatar

Record at least one minute video of your Avatar subject and upload it to an external hosting service (e.g. Amazon S3).

👍

Footage Tips:

  • Keep the subject's face visible at all times
  • The subject must face the camera directly
  • Record the subject in a quiet, well lit environment
  • Make sure the subject’s mouth is closed when pausing between sentences
  • The Submitted video must be at least 1 minute long

2. Create the Express Avatar

POST https://api.d-id.com/scenes/avatars | Create an Express Avatar

{
  "name": "Alex",
  "consent_id": "cst_CgeFQXJD2PHelloMINPQHnY",
  "show": "true",
  "persist": "true",
  "source_url": "https://yourwebsite.storage.com/AlexVideoFile.mp4",
  "webhook": "webhook.site/alex_avatarcreation_result",
  "thumbnail_url": "https://yourwebsite.storage.com/AlexThumbnail.png",
 
}

{
  "id": "avt_GvcBonjourY5P_pmX5tgS",
  "object": "scene_avatar",
  "created_at": "2024-09-19T14:41:35.918Z",
  "status": "validating"
}
  • The Express Avatarname of the should match the "[user name]" pronounced in the recorded consent video.
  • Place the consent_id returned in the first Consent step.

3. Fetch the Express Avatar

Fetch the created Express Avatar's status and properties.
To make the avatar speak with a cloned voice, save the voice_id for the next step.

GET https://api.d-id.com/scenes/avatars/id | Get a specific Express Avatar

{
    "object": "scene_avatar",
    "owner_id": "userID",
    "id": "avt_abcd123",
    "status": "done",
    "created_at": "2024-10-08T15:00:41.115Z",
    "created_by": "userID",
    "modified_at": "2024-10-08T15:07:15.811Z",
    "started_at": "2024-10-08T15:03:26.047",
    "completed_at": "2024-10-08T15:07:13.172",
    "name": "Alex",
    "thumbnail_url": "https://scenes-avatars.d-id.com/userID/avt_abcd123/thumbnail.png",
    "talking_preview_url": "https://scenes-avatars.d-id.com/userID/avt_abcd123/talking-preview.mp4",
    "image_url": "https://scenes-avatars.d-id.com/userID/avt_abcd123/image.png",
    "voice_id": "IfhpAQ4yN4MQ9ykyw3iK",
    "source_url": "https://scenes-avatars.d-id.com/userID/avt_abcd123/video.mp4",
    "persist": true,
    "preview_url": ""
}

To see all of the created Express Avatars, use the Get Express Avatars endpoint.

📘

Note

You can proceed only when the Avatar's status is "status": "done"

➤✴️ Video Creation

1. Create a Scene with your Express Avatar

Use the id (from the previous step) and place it in the avatar_id property.
To use the cloned voice created automatically in the creation process, make sure to include the voice_id fetched from the previous step.

POST https://api.d-id.com/scenes | Create a Scene

{
    "avatar_id": "avt_abcd123",
    "script": {
        "type": "text",
        "input": "This is what the avatar will say!",
        "provider": {
            "type": "elevenlabs",
            "voice_id": "VOICE_ID_FROM_GET_AVATAR_ID"
        }
    },
    "webhook": "webhook.site/alex_avatarcreation_result"
}

{
    "object": "scene",
    "id": "scn_xyz1234",
    "created_at": "2024-10-10T13:37:01.991Z",
    "status": "created"
}

👍

Use Webhooks!

Create an endpoint that accepts POST requests, and add it to the webhook field.
This endpoint will be triggered once the video is ready.


2. Get the Scene Video

GET https://api.d-id.com/scenes/{id} | Get a specific Scene

{
    "owner_id": "userID",
    "id": "scn_xyz12345",
    "created_at": "2024-10-10T13:37:01.991Z",
    "modified_at": "2024-10-10T13:37:34.805Z",
    "created_by": "userID",
    "avatar_id": "avt_abcd1234",
    "status": "started",
    "audio_url": "s3://d-id-scenes-prod/userID/scn_xyz12345/elevenlabs.wav",
    "pending_url": "s3://d-id-scenes-prod/userID/scn_xyz12345E/result.mp4",
    "started_at": "2024-10-10T13:37:02.079",
    "completed_at": "2024-10-10T13:37:34.671",
    "thumbnail_url": "s3://d-id-scenes-avatars-persistent-prod/userID/avt_abcd1234/thumbnail.png"
}

📘

Note

The output video will be located in the result_url field only when "status": "done"


✴️ Support


 Have any questions? We are here to help! Please leave your question in the Discussions section and we will be happy to answer shortly.

Ask a question