API Reference

Avatar

The avatar family turns a portrait and a voice track into a talking video, or re-syncs the mouth of a person in an existing video to new audio. It is four endpoints that work as a preparation chain: two of them produce handles (audio_id, session_id) that the two generation endpoints consume.

POST /v1/audio/tts              → audio_id ──┐
                                             ├──> POST /v1/avatar/generations
POST /v1/avatar/identify-face   → session_id ┴──> POST /v1/avatar/lip-sync

Endpoints

Page	Endpoint	Model ID	Mode
Text to Speech	`POST /v1/audio/tts`	`kling-tts`	Synchronous
Face Recognition	`POST /v1/avatar/identify-face`	`kling-face-recognition`	Synchronous
Clip Generation	`POST /v1/avatar/generations`	`kling-avatar`	Asynchronous
Lip-Sync	`POST /v1/avatar/lip-sync`	`kling-lip-sync`	Asynchronous

model selects routing and pricing only. The endpoint you post to decides which operation runs.

Send async: true on the two generation endpoints

Without it, Clip Generation and Lip-Sync block until the video is finished, which takes minutes and will outlast most client timeouts. With "async": true you get an id back immediately and poll for the result. Text to Speech and Face Recognition are quick and always answer synchronously.

End-to-end example

API_KEY=<API_KEY>; H=https://llm.siraya.ai

# 1. voice track
AUDIO_ID=$(curl -sS $H/v1/audio/tts -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' -d '{
    "model": "kling-tts", "text": "Hello from Siraya AI, this is a lip sync test.",
    "voice_id": "oversea_male1", "voice_language": "en", "voice_speed": 1
  }' | python3 -c 'import json,sys;print(json.load(sys.stdin)["audio_id"])')

# 2. clip generation: portrait + that voice
curl -sS $H/v1/avatar/generations -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' -d "{
    \"model\": \"kling-avatar\",
    \"image\": \"https://your-domain.com/portrait.png\",
    \"audio_id\": \"$AUDIO_ID\",
    \"prompt\": \"A person talking happily to the camera\",
    \"mode\": \"std\", \"async\": true
  }"

# 3. lip-sync needs a session from a face pass first
SESSION=$(curl -sS $H/v1/avatar/identify-face -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' -d '{
    "model": "kling-face-recognition",
    "video_url": "https://your-domain.com/source.mp4"
  }' | python3 -c 'import json,sys;print(json.load(sys.stdin)["session_id"])')

curl -sS $H/v1/avatar/lip-sync -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' -d "{
    \"model\": \"kling-lip-sync\", \"session_id\": \"$SESSION\",
    \"face_choose\": [{
      \"face_id\": \"-1\", \"audio_id\": \"$AUDIO_ID\",
      \"sound_start_time\": 0, \"sound_end_time\": 3000, \"sound_insert_time\": 0,
      \"sound_volume\": 1, \"original_audio_volume\": 1
    }],
    \"async\": true
  }"

# 4. poll — each generation has its own status endpoint
curl -sS $H/v1/avatar/generations/<AVATAR_VIDEO_ID> -H "Authorization: Bearer $API_KEY"
curl -sS $H/v1/avatar/lip-sync/<LIP_SYNC_VIDEO_ID>  -H "Authorization: Bearer $API_KEY"

Not supported

Kling parameter	This platform
`callback_url`	Refused — poll the GET endpoints instead
`external_task_id`	Refused — use the `id` this platform returns
`video_id` (face recognition)	Not exposed — always send `video_url`

Spellings from the other video endpoints are refused by name rather than ignored: on Clip Generation and Lip-Sync, image_url / frame_images / input_references are not valid material fields (clip generation takes image), and seconds / resolution / aspect_ratio have no meaning here.

Errors

Status	Meaning
`400`	Invalid parameter — the message names the field and often the upstream constraint text, e.g. `The model did not detect a human`, `soundVolume: must be less than or equal to 2.0`
`401`	Invalid API key
`404`	Unknown model
`503`	Every upstream route is unavailable — retry later

Official references

Value sets that Kling owns and this platform passes through unchanged:

What	Where
Voice list (`voice_id` + its language)	Kling AI Voice List
Model × mode (`std`/`pro`) support matrix	Capability Map
TTS parameter reference	text-to-speech
Face recognition input rules	face-detection
Avatar parameter reference	avatar/image2video
Lip-sync parameter reference	advanced-lip-sync