Timbre Library API

Updated: 2026-07-14

Overview

Query the timbre library available to the account bound to the API Key.
Supports paginated public timbre queries.
The server resolves the real user ID from the API Key. The user identity is recognized automatically, and userId is not required.

Base URL

https://video-translation.viitor.com

Authentication

Authorization: Bearer vt_live_xxx

The OpenAPI server resolves the real user ID from the API Key.

Common Response Structure

Field	Type	Description
`code`	Integer	`0` means success; non-zero means failure
`message`	String	Response message
`data`	Object	Business data

For paginated endpoints, the data structure is:

Field	Type	Description
`current`	Integer	Current page
`size`	Integer	Page size
`total`	Long	Total records
`pages`	Integer	Total pages
`records`	Array	Records on the current page

sortType Enum

The public timbre pagination endpoint supports sortType.

Value	Description
`0`	Default sort
`1`	Trending
`2`	Most used
`3`	Publish time
`4`	Timbre name
`6`	Most characters generated

Query Public Timbres

Endpoint

Request URL: https://video-translation.viitor.com/openapi/v1/timbre/open/pageList
Method: POST
Content-Type: application/json

HTTP Headers

Header	Required	Type	Description
`Content-Type`	Yes	String	`application/json;charset=UTF-8`
`Accept`	Recommended	String	`application/json;charset=UTF-8`
`Authorization`	Yes	String	`Bearer <API_KEY>`

Request Body

Field	Type	Required	Description
`current`	Integer	No	Current page. Default: `1`
`pageSize`	Integer	No	Page size. Default: `12`, maximum: `400`
`timbreName`	String	No	Timbre name. Supports fuzzy search
`sortType`	Integer	No	Sort type. Default: `0`

Successful `records` Fields

Field	Type	Description
`timbreId`	Integer	Timbre ID
`timbreName`	String	Timbre name
`timbreEnglishName`	String	English timbre name
`voiceName`	String	Voice identifier. Can be used as `voiceName` for speech synthesis
`vocalAudioUrl`	String	Vocal audio URL
`avatarUrl`	String	Timbre avatar URL
`createTime`	Long	Creation time
`common`	Integer	Timbre type. `1` means public timbre

Request Example

curl -X POST "https://video-translation.viitor.com/openapi/v1/timbre/open/pageList" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vt_live_xxx" \
  -d '{
    "current": 1,
    "pageSize": 10,
    "timbreName": "Nathan",
    "sortType": 1
  }'

Successful Response Example

{
  "code": 0,
  "message": "OK",
  "data": {
    "current": 1,
    "size": 10,
    "total": 1,
    "pages": 1,
    "records": [
      {
        "timbreId": 16391,
        "timbreName": "博文老师",
        "timbreEnglishName": "NathanNarrator",
        "voiceName": "CHINESE_SC_NARR_DOC",
        "vocalAudioUrl": "https://tts-ap-singapore-1306922583.cos.accelerate.myqcloud.com/ref_audios/CHINESE_SC_NARR_DOC.wav",
        "avatarUrl": "https://viitor-cdn.viitor.com/timbre_library/avatar/202509019/1f777c23ce07408d985ce3c63fc334f4.jpg",
        "common": 1
      }
    ]
  }
}

Common Error Codes

code	message	Description
`0`	`OK`	Success
`1103`	`No Privilege`	The account is not VIP or has no permission to call the API
`2001`	`Invalid Parameter`	Invalid parameter
`400001`	`missing_api_key`	Missing API Key
`400002`	`invalid_api_key`	Invalid API Key
`400003`	`disabled_api_key`	API Key is disabled
`400004`	`expired_api_key`	API Key has expired

Timbre Library API

© 2026 HighRas Limited