CreateVoiceConversation
1. API Description
Domain name for API request: trtc.intl.tencentcloudapi.com.
This API is used to create an AI conversation task.
A maximum of 20 requests can be initiated per second for this API.
2. Input Parameters
The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| Action | Yes | String | Common Params. The value used for this API: CreateVoiceConversation. |
| Version | Yes | String | Common Params. The value used for this API: 2019-07-22. |
| Region | Yes | String | Common Params. For more information, please see the list of regions supported by the product. This API only supports: ap-guangzhou, ap-hongkong, ap-singapore. |
| SdkAppId | Yes | Integer | The TRTC SdkAppId. It must be the same SdkAppId as the conversation room. |
| RoomId | Yes | String | Room ID of the TRTC room where the conversation runs. Room IDs are numeric by default. If the room ID is a string, set RoomIdType to 1. |
| RoomIdType | Yes | Integer | Room ID type. It must match the room ID type of the conversation room. 0 is a numeric room ID, and 1 is a string room ID. Valid values: - 0: numeric room ID (Default) - 1: string room ID |
| AgentConfig | Yes | VoiceConversationConfig | Chatbot configuration. |
| ConversationMode | No | String | Conversation pipeline mode: Cascade (default, three-stage pipeline) or S2S (end-to-end speech-to-speech model).Valid values: - Cascade: three-stage pipeline (default). Speech recognition, a large language model, and text-to-speech. - S2S: end-to-end speech-to-speech model. Default: Cascade |
| S2SConfig | No | VoiceConversationS2SConfig | End-to-end speech-to-speech model configuration. Required only in S2S mode. Ignored in Cascade mode. |
| STTConfig | No | VoiceConversationSTTConfig | Speech recognition configuration. Required only in |
| LLMConfig | No | VoiceConversationLLMConfig | Large language model (LLM) configuration. Required only in Cascade mode. Ignored in S2S mode. |
| TTSConfig | No | VoiceConversationTTSConfig | Text to speech configuration. Required only in |
| DialogConfig | No | VoiceConversationDialogConfig | Conversation control configuration. Not supported in S2S mode. |
| VisionConfig | No | VoiceConversationVisionConfig | Visual understanding configuration. Not supported in S2S mode. |
3. Output Parameters
| Parameter Name | Type | Description |
|---|---|---|
| TaskId | String | Unique ID of the conversation task, generated by the Tencent Cloud server. Later requests that query or control the task must include this TaskId. |
| RequestId | String | The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem. |
4. Example
Example1 Start a conversation task (three-segment)
Input Example
POST / HTTP/1.1
Host: trtc.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateVoiceConversation
<Common request parameters>
{
"SdkAppId": 1400000311,
"RoomId": "99884336",
"RoomIdType": 0,
"AgentConfig": {
"UserId": "test2",
"UserSig": "eJyrVgrxCdYrzkxXslJQyvEsqDTzcyrzyHGNcgoMKsuudEt2D3D1KUwsi8jy8PD3NQnK********************************************************************cmWpRSDrjPQMYKaUZOaCzTA3MzYwMDI2NYOKZ6ak5pVkpmVCNJSkFpcYKdUCAKlEMxg_",
"TargetUserId": [
"Jeff"
],
"TTSPushRoomParams": {
"UserId": "tts-bot-001"
},
"MaxIdleTime": 5000,
"FilterBracketsContent": [
1
],
"SubtitleMode": 0,
"TurnDetectionMode": "auto"
},
"ConversationMode": "Cascade",
"STTConfig": {
"Provider": "trtc",
"Params": "{\"engine_model_type\":\"bigmodel\", \"max_speak_time\":\"60000\", \"language\":\"zh\"}"
},
"LLMConfig": {
"LLMType": "tencent",
"Model": "hunyu*****0628",
"APIUrl": "http://api.taiji.w*****************/chat/completions",
"APIKey": "n21LYT6WmpE***********mqWKCrQlzJ",
"SystemPrompt": "You are a concise dialogue assistant.",
"FailureMessage": "System busy, try again later",
"MaxTokens": 0,
"ThinkingMode": false,
"MaxHistory": 50,
"MaxToolRound": 20,
"Timeout": 60000,
"Temperature": 0.5,
"TopP": 0.9,
"McpServer": {
"Name": "weath****ools",
"Url": "https://m*********e.com/sse",
"Timeout": 10000,
"Headers": [
{
"Key": "enable_search",
"Value": "true"
}
],
"ToolList": [
"get_****her"
]
},
"CustomHeaders": [
{
"Key": "X-Request-Source",
"Value": "trtc-conversation"
}
],
"CustomFields": [
{
"Key": "enable_search",
"Value": "true"
}
],
"HistoryMessages": [
{
"Role": "user",
"Content": "Hello"
}
]
},
"TTSConfig": {
"Provider": "trtc",
"Params": "{\"model\":\"flow_02_turbo\",\"voice_id\":\"v-female-R2s4N9qJ\",\"speed\":1.0,\"volume\":1.0,\"pitch\":0}"
},
"DialogConfig": {
"InterruptMode": 2,
"InterruptSpeechDuration": 200,
"InterruptKeywords": [
Stop
],
"SilenceFollowUp": 50,
"SilenceFollowUpText": "Are you still there? Tell me directly if you have any questions.",
"WelcomeMessage": "Hello, I'm your ai assistant. What can I do for you?"
},
"VisionConfig": {
"Enable": true,
"StorageType": 0
},
"SpeechPushConfig": {
"Url": "ws://21.********22:9002",
"Token": "test***ken"
}
}Output Example
{
"Response": {
"TaskId": "-nG0jIFU7iHfG3DHVsI24YFXEn*************************bRRKvrG-CxBxuPyrGvSr2ZQE.",
"RequestId": "45192e66-a49e-4ea4-92f0-519955e3c903"
}
}Example2 Start a conversation task (end-to-end large speech model)
Input Example
POST / HTTP/1.1
Host: trtc.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateVoiceConversation
<Common request parameters>
{
"SdkAppId": 1400704311,
"RoomId": "9988123",
"RoomIdType": 0,
"AgentConfig": {
"UserId": "test2",
"UserSig": "eJyrVgrxCdYrzkxXslJQyvEsqDTzcyrzyHGNcgoMKsuudEt2D3D1KUwsi8jy8PD3NQnK********************************************************************cmWpRSDrjPQMYKaUZOaCzTA3MzYwMDI2NYOKZ6ak5pVkpmVCNJSkFpcYKdUCAKlEMxg_",
"TargetUserId": [
"Jeff"
],
"TTSPushRoomParams": {
"UserId": "tts-bot-001"
},
"MaxIdleTime": 50
},
"ConversationMode": "S2S",
"S2SConfig": {
"Provider": "doubao",
"Params": "{\"api_key\":\"xxxxxx\",\"type\":\"session.create\",\"session\":{\"id\":\"\",\"model\":\"1.2.6.1\",\"instructions\":\"You are an everyday-life assistant. You are good at answering daily questions about recipes, travel, parenting, health, shopping, and legal matters. Please answer concisely and clearly in Chinese.\",\"type\":\"realtime\",\"audio\":{\"input\":{\"format\":{\"type\":\"pcm\",\"rate\":16000}},\"output\":{\"format\":{\"type\":\"pcm_s16le\",\"rate\":24000},\"voice\":\"zh_female_vv_jupiter_bigtts\"}}},\"extension\":{\"asr\":{\"extra\":{}},\"dialog\":{\"bot_name\":\"Doubao\"},\"tts\":{\"speaker\":\"zh_female_vv_jupiter_bigtts\",\"audio_config\":{\"channel\":1,\"format\":\"pcm_s16le\",\"sample_rate\":24000}}}}"
}
}Output Example
{
"Response": {
"TaskId": "-nG0jIFU7g8UyQOwf8uvyfe1ph*************************bAp-C8HdhuD+Acd+5Tavn6AE.",
"RequestId": "32151e30-fd9f-47d4-b59d-72a372eb61f0"
}
}5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
- Tencent Cloud SDK 3.0 for Python
- Tencent Cloud SDK 3.0 for Java
- Tencent Cloud SDK 3.0 for PHP
- Tencent Cloud SDK 3.0 for Go
- Tencent Cloud SDK 3.0 for Node.js
- Tencent Cloud SDK 3.0 for .NET
- Tencent Cloud SDK 3.0 for C++
Command Line Interface
6. Error Code
The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.
| Error Code | Description |
|---|---|
| AuthFailure | CAM signature/authentication error. |
| AuthFailure.UnauthorizedOperation | CAM authentication failed. |
| AuthFailure.UnsupportedOperation | Unsupported operation. |
| FailedOperation | Operation failed. |
| InternalError | Internal error. |
| InvalidParameter | Parameter error. |
| InvalidParameter.OutOfRange | Parameter value is out of range. |
| InvalidParameter.SdkAppId | SdkAppId is incorrect. |
| MissingParameter | Missing parameter. |
| MissingParameter.Region | Region parameter missing. |
| MissingParameter.RoomId | RoomId is missing. |
| MissingParameter.SdkAppId | SdkAppId is missing. |
| MissingParameter.UserId | Missing UserId parameter. |
| MissingParameter.UserSig | UserSig parameter missing. |
| UnsupportedOperation | Unsupported operation. |
