Generate avatar video

January 12, 2026 (October 20, 2026)

Table of contents

  1. Request Headers
  2. Request Body
    1. Avatar Source (one required)
    2. Audio Source (one required)
    3. TTS Options (when using text)
    4. Video Options
    5. Scheduler Parameters
  3. Responses
  4. Model
  5. Examples
  6. Try It

This endpoint generates a lip-sync video from an avatar image and audio. The avatar speaks with realistic lip movements synchronized to the provided audio or generated text-to-speech.

You can use either:

  • A saved avatar from POST /avatars or system templates
  • A direct image URL

For audio, you can provide either:

  • A pre-recorded audio file URL (upload via POST /assets)
  • Text that will be converted to speech using TTS

https://api.useapi.net/v1/kling/avatars/video

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/json
Request Body 
{
  "email": "[email protected]",
  "avatarId": "123456789012",
  "text": "Hello, welcome to our product demo!",
  "speakerId": "speaker_id_123"
}
  • email is optional. Leave it out and the job goes to one of your accounts that has a free job slot, picked at random. Each account runs at most its maxJobs jobs at once, and GET scheduler/available shows the free slots. If no account has a free slot, the response is 429.
    Pass email to run the job on that account (429 if it is busy). Uploaded files, elements, voices, avatars and earlier tasks belong to one account, so pass the email of the account they came from.
    With more than one account, reading the task with GET tasks/task_id needs its account’s email. The response’s task.userId is that account’s session.userId in GET accounts, and GET scheduler lists each running task with its email.
Avatar Source (one required)

Provide either avatarId or imageUrl, not both:

  • avatarId is the ID of a saved avatar. Use GET /avatars to list your personal avatars or browse system templates. When using an avatar, its saved prompt and TTS settings are used as defaults.

  • imageUrl is a direct URL to an avatar image. You can upload images using POST /assets and use the returned URL here.

Audio Source (one required)

Provide either audioUrl or text, not both:

  • audioUrl is a URL to a pre-recorded audio file. You can upload audio using POST /assets and use the returned URL here.

  • text is the text to be converted to speech. Maximum length: 5000 characters. Requires speakerId to be provided.

TTS Options (when using text)

These options apply when providing text for text-to-speech:

  • speakerId is required when using text. Use GET /tts/voices to get available speaker IDs. If using an avatarId, the avatar’s saved ttsSpeaker is used as default.

  • speed is optional, speech speed. Range: 0.8 to 2.0. Default: 1. If using an avatarId, the avatar’s saved ttsSpeed is used as default.

  • emotion is optional, speech emotion. Supported values: neutral (default), happy, angry, sad, fearful, disgusted, surprised. Not all emotions are available for all speakers. Check GET /tts/voices for each speaker’s supported emotions. If using an avatarId, the avatar’s saved ttsEmotionKey is used as default.

Video Options

  • prompt is optional, description of the avatar’s behavior/appearance. Maximum length: 2000 characters. If using an avatarId, the avatar’s saved prompt is used as default. Default: “Natural speaking”.

  • mode is optional, the video generation mode. Supported values: std (default), pro.

Scheduler Parameters

  • maxJobs is optional, range from 1 to 50. Specifies the maximum number of concurrent jobs.

  • replyUrl is optional, a callback URL to receive generation progress and result. See GET /tasks/task_id for response model.

  • replyRef is optional, a reference identifier for the callback.

Responses

  • 200 OK

    {
  "task": {
    "id": 123456789,
    "userId": 12345,
    "type": "m2v_img2digital",
    "scene": "NORMAL_CREATION",
    "status": 5,
    "status_name": "submitted",
    "status_final": false,
    "taskInfo": {
      "type": "m2v_img2digital",
      "inputs": [
        {
          "name": "image",
          "inputType": "URL",
          "url": "https://s21-kling.klingai.com/ai-platform/.../avatar.jpg"
        },
        {
          "name": "audio",
          "inputType": "URL",
          "url": "https://s21-kling.klingai.com/ai-platform/.../audio.mp3"
        }
      ],
      "arguments": [
        { "name": "prompt", "value": "Natural speaking" },
        { "name": "upload_method", "value": "MY_AVATAR" },
        { "name": "duration", "value": "5.234" },
        { "name": "model_mode", "value": "std" }
      ]
    },
    "createTime": 1736640000000,
    "updateTime": 1736640000000
  },
  "status": 5,
  "status_name": "submitted",
  "status_final": false
}

  • 400 Bad Request

    The parameters are invalid. When Kling refuses the submitted parameters, error carries Kling’s own message.

    {
  "error": "<error message>"
}

  • 401 Unauthorized

    {
  "error": "Unauthorized",
  "code": 401
}

  • 404 Not Found

    {
  "error": "<error message>"
}
Model 
{ // TypeScript, all fields are optional
  task: {
    id: number
    userId: number
    type: string
    scene: string
    status: number
    status_name: 'submitted' | 'failed' | 'processing' | 'succeed'
    status_final: boolean
    taskInfo: {
      type: string
      inputs: { name: string, inputType: string, url: string }[]
      arguments: { name: string, value: string }[]
    }
    createTime: number
    updateTime: number
  }
  works: object[]
  status: number
  status_name: string
  status_final: boolean
  message: string
}
Examples 
  • curl -X POST "https://api.useapi.net/v1/kling/avatars/video" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ..." \
   -d '{
     "email": "[email protected]",
     "avatarId": "123456789012",
     "text": "Welcome to our demo!",
     "speakerId": "speaker_id_123"
   }'

  • const token = "API token";
const email = "Previously configured account email";
const apiUrl = "https://api.useapi.net/v1/kling/avatars/video";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    email: email,
    avatarId: "123456789012",
    text: "Welcome to our demo!",
    speakerId: "speaker_id_123"
  })
});
const result = await response.json();
console.log("response", {response, result});

  • import requests
token = "API token"
email = "Previously configured account email"
apiUrl = "https://api.useapi.net/v1/kling/avatars/video"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "email": email,
    "avatarId": "123456789012",
    "text": "Welcome to our demo!",
    "speakerId": "speaker_id_123"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
Try It