Create avatar video · DeutschlandGPT

Starts an asynchronous talking-head avatar video job (HeyGen). The avatar reads the supplied script in the chosen voice.

Returns a job descriptor with status: "pending". Poll GET /v2/videos/avatar-generations/{id} until status is succeeded (returns a signed URL) or failed. Generation typically takes 60–300 seconds.

The rendered duration is unknown up front, so credits are pre-charged from an estimate based on the script length and reconciled to the real duration on completion (any difference is refunded).

POSThttps://api.deutschlandgpt.de/v2/videos/avatar-generationsTry it

Example request

curl https://api.deutschlandgpt.de/v2/videos/avatar-generations \
  -X POST \
  -H "Authorization: Bearer $DGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script": "Hi! Welcome to DeutschlandGPT — let me show you what our platform can do.",
  "model": "heygen-avatar-v2",
  "avatar_id": "Daisy-inskirt-20220818",
  "voice_id": "1bd001e7e50f421d891986aad5158bc8",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "speed": 0,
  "background_color": "#FFFFFF"
}'

curl https://api.deutschlandgpt.de/v2/videos/avatar-generations \
  -X POST \
  -H "Authorization: Bearer $DGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script": "Hi! Welcome to DeutschlandGPT — let me show you what our platform can do.",
  "model": "heygen-avatar-v2",
  "avatar_id": "Daisy-inskirt-20220818",
  "voice_id": "1bd001e7e50f421d891986aad5158bc8",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "speed": 0,
  "background_color": "#FFFFFF"
}'

import os, requests

response = requests.post(
    "https://api.deutschlandgpt.de/v2/videos/avatar-generations",
    headers={"Authorization": f"Bearer {os.environ['DGPT_API_KEY']}"},
    json={
        "script": "Hi! Welcome to DeutschlandGPT — let me show you what our platform can do.",
        "model": "heygen-avatar-v2",
        "avatar_id": "Daisy-inskirt-20220818",
        "voice_id": "1bd001e7e50f421d891986aad5158bc8",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "speed": 0,
        "background_color": "#FFFFFF"
    },
)

print(response.json())

import os, requests

response = requests.post(
    "https://api.deutschlandgpt.de/v2/videos/avatar-generations",
    headers={"Authorization": f"Bearer {os.environ['DGPT_API_KEY']}"},
    json={
        "script": "Hi! Welcome to DeutschlandGPT — let me show you what our platform can do.",
        "model": "heygen-avatar-v2",
        "avatar_id": "Daisy-inskirt-20220818",
        "voice_id": "1bd001e7e50f421d891986aad5158bc8",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "speed": 0,
        "background_color": "#FFFFFF"
    },
)

print(response.json())

const response = await fetch('https://api.deutschlandgpt.de/v2/videos/avatar-generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DGPT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "script": "Hi! Welcome to DeutschlandGPT — let me show you what our platform can do.",
    "model": "heygen-avatar-v2",
    "avatar_id": "Daisy-inskirt-20220818",
    "voice_id": "1bd001e7e50f421d891986aad5158bc8",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "speed": 0,
    "background_color": "#FFFFFF"
  }),
});

console.log(await response.json());

const response = await fetch('https://api.deutschlandgpt.de/v2/videos/avatar-generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DGPT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "script": "Hi! Welcome to DeutschlandGPT — let me show you what our platform can do.",
    "model": "heygen-avatar-v2",
    "avatar_id": "Daisy-inskirt-20220818",
    "voice_id": "1bd001e7e50f421d891986aad5158bc8",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "speed": 0,
    "background_color": "#FFFFFF"
  }),
});

console.log(await response.json());

Request body

scriptstringrequired

The text the avatar will speak. Capped per-model (HeyGen ~1500 characters).

modelstringoptional

Avatar video model. Defaults to heygen-avatar-v2.

avatar_idstringoptional

Avatar to use. Defaults to the model's default avatar. Discover avatars via HeyGen's GET /v2/avatars.

voice_idstringoptional

Voice to use. Defaults to the model's default voice. Discover voices via HeyGen's GET /v2/voices.

aspect_ratiostringoptional

Aspect ratio. Must be supported by the model (16:9, 9:16, 1:1).

resolutionstringoptional

Output resolution. Must be supported by the model (720p, 1080p).

speednumberoptional

Speech speed multiplier passed to the voice.

background_colorstringoptional

Solid background colour as a hex string.

Response

200application/json

{
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "avatar_video.generation_job",
  "status": "pending",
  "model": "string",
  "created": 0,
  "params": {
    "avatarId": "string",
    "voiceId": "string",
    "resolution": "string",
    "aspectRatio": "string",
    "estimatedDurationSeconds": 0
  },
  "estimated_cost_in_euro": 0
}

{
  "id": "00000000-0000-0000-0000-000000000000",
  "object": "avatar_video.generation_job",
  "status": "pending",
  "model": "string",
  "created": 0,
  "params": {
    "avatarId": "string",
    "voiceId": "string",
    "resolution": "string",
    "aspectRatio": "string",
    "estimatedDurationSeconds": 0
  },
  "estimated_cost_in_euro": 0
}

Job accepted; poll the GET endpoint with the returned id.

idstring<uuid>

objectstring

statusstring

modelstring

createdinteger

Unix timestamp

paramsobject

avatarIdstring

voiceIdstring

resolutionstring

aspectRatiostring

estimatedDurationSecondsinteger

estimated_cost_in_euronumber

Upper bound on cost charged at job creation. Reconciled to actual duration on completion.

Response codes

200

Job accepted; poll the GET endpoint with the returned id.

object

400

Script too long, or unsupported resolution/aspect ratio for this model

401

Unauthorized

402

Insufficient credits

403

API key lacks permission for this model

404

Model not found