The resources (image, video, voice) generated by our API are valid for 7 days.
Please save the relevant resources as soon as possible to prevent expiration.
To experience our live avatar streaming feature in action, explore our demo built on the Agora streaming service: AKool Streaming Avatar React Demo.
Knowledge Base Integration: You can enhance your streaming avatar with contextual AI responses by integrating a Knowledge Base. When creating a session, provide a knowledge_id parameter to enable the AI to use documents and URLs from your knowledge base for more accurate and relevant responses.
POST https://openapi.akool.com/api/open/v3/avatar/create
Request Headers
Parameter
Type
Required
Description
Authorization
String
Yes
Bearer token for API authentication. Obtain from Get Token endpoint.
Body Attributes
Parameter
Type
Value
Description
url
String
Avatar resource link. It is recommended that the video be about one minute long, and the avatar in the video content should rotate at a small angle and be clear.
avatar_id
String
avatar unique ID，Can only contain /^a-zA-Z0-9/.
name
String
Avatar display name for easier identification and management.
type
String
2
Avatar type 2 represents stream avatar, When type is 2, you need to wait until status is 3 before you can use it, You can get the current status in real time through the interface Get Avatar Detail API.
url_from
Number
1，2
url source, 1 means akool and other links, 2 means other third-party links (currently only supports YouTube / TikTok / X / Google Drive)
Response Attributes
Parameter
Type
Value
Description
code
int
1000
Interface returns business status code(1000:success)
msg
String
OK
Interface returns status information
data
Object
{ avatar_id: "xx", url: "", status: 1 }
avatar_id: Used by creating live avatar interface. url: You can preview the avatar via the link. status: 1-queueing, 2-processing, 3-success, 4-failed
Session duration in seconds (max: 3600). Credits are pre-charged for the full duration, but any unused credits will be refunded after the session ends. Rates depend on your subscription plan. See our API Pricing for details.
knowledge_id
String
No
Knowledge base ID to provide context for AI responses. Create and manage knowledge bases using the Knowledge Base API. When provided, the AI will use documents and URLs from the knowledge base to enhance response accuracy.
voice_id
String
No
Voice ID to change avatar’s voice. Get valid IDs from Voice List API
voice_url
String
No
Custom voice model URL. Get valid URLs from Voice List API
language
String
No
Language code to use for the session. Get valid codes from Language List API
Stream type to use for the session. “agora” = Agora (default), “livekit” = Livekit, “trtc” = TRTC
credentials
Object
No
Optional. Provide credentials so AKool’s streaming avatar can join your stream.
Voice Parameters
Parameter
Type
Required
Description
speed
double
No
Controls the speed of the generated speech. Values range from 0.8 to 1.2, with 1.0 being the default speed.
pron_map
Object
No
Pronunciation mapping for custom words. Example: “pron_map”: { “akool” : “ai ku er” }
Credentials
Parameter
Type
Required
Description
agora_uid
Number
Required when stream_type is “agora”
Agora SDK user ID.
agora_app_id
String
Optional when stream_type is “agora”
Agora App ID.
agora_channel
String
Required when stream_type is “agora”
Agora channel name.
agora_token
String
Required when stream_type is “agora”
Agora access token.
livekit_url
String
Required when stream_type is “livekit”
Livekit server URL.
livekit_token
String
Required when stream_type is “livekit”
Livekit access token.
livekit_room_name
String
Optional when stream_type is “livekit”
Livekit room name.
livekit_server_identity
String
Optional when stream_type is “livekit”
Livekit server identity.
livekit_client_identity
String
Optional when stream_type is “livekit”
Livekit client identity.
trtc_sdk_app_id
Number
Required when stream_type is “trtc”
TRTC App ID.
trtc_sdk_room_id
String
Required when stream_type is “trtc”
TRTC room ID.
trtc_sdk_user_id
String
Required when stream_type is “trtc”
TRTC user ID.
trtc_sdk_user_sig
String
Required when stream_type is “trtc”
TRTC authentication token (userSig).
Response Parameters
Parameter
Type
Value
Description
code
int
1000
Interface returns business status code(1000:success)
msg
String
Interface returns status information
data
Object
{ "_id": "", "status": 1, "credentials": {} }
_id: Interface returns data, status: the status of session: [1:queueing, 2:processing, 3:completed, 4:failed], credentials: the join information for the Agora SDK
ExampleBody
Copy
{ "_id": "6698c9d69cf7b0d61d1b6420", "status": 1, "stream_type": "agora", "credentials": { "agora_uid": 100000, // The user ID for the Agora SDK. "agora_app_id": "", // The App ID used for the Agora SDK. "agora_channel": "", // The specified channel name for the Agora SDK. "agora_token": "", // The authentication token for the Agora SDK, currently the valid time is 5 minutes. }}
{ "code": 1000, "msg": "OK", "data": { "_id": "6698c9d69cf7b0d61d1b6420", "uid": 100010, "type": 1, "status": 1, "stream_type": "agora", "credentials": { "agora_uid": 100000, // The user ID for the Agora SDK. "agora_app_id": "", // The App ID used for the Agora SDK. "agora_channel": "", // The specified channel name for the Agora SDK. "agora_token": "", // The authentication token for the Agora SDK, currently the valid time is 5 minutes. } }}
{ "code": 1000, "msg": "OK", "data": { "_id": "6698c9d69cf7b0d61d1b6420", "uid": 100010, "type": 1, "status": 3, "stream_type": "agora", "credentials": { "agora_uid": 100000, // The user ID for the Agora SDK. "agora_app_id": "", // The App ID used for the Agora SDK. "agora_channel": "", // The specified channel name for the Agora SDK. } }}
{ "code": 1000, "msg": "OK", "data": { "count": 18, "result": [ { "_id": "666d3006247f07725af0f884", "uid": 100010, "type": 1, "status": 1, "stream_type": "agora", "credentials": { "agora_uid": 100000, // The user ID for the Agora SDK. "agora_app_id": "", // The App ID used for the Agora SDK. "agora_channel": "" // The specified channel name for the Agora SDK. }, } ] }}
