OpenAPI Integration

Base URL: https://app.duix.ai/

1. Prerequisites

Generate Signature and Obtain Token

When integrating with the duix-openapi-v2 platform, you must generate access tokens in your own backend.
Refer to the token guide for implementation details:
How to Get Token

2. Management Interfaces

All management endpoints require a valid token in the HTTP request header.

Interaction Flow

2.1 Get App Real-Time Concurrency

Endpoint: /duix-openapi-v2/sdk/v2/getconcurrentNumber
Method: GET
Description: Retrieve the real-time concurrency status of an application.

Parameters

Name	Type	Location	Description
appId	String	Query	Application ID created on the Duix platform

Response

Name	Type	Description
code	String	Response code
data	ConcurrentStatus	Concurrency details
cropId	String	Corporate ID
totalConcurrentNumber	integer	Total concurrent sessions
userConcurrentNumber	integer	User-specific concurrent sessions
message	String	Response message
success	boolean	Request status

Example Response

{
  "code": "",
  "data": {
    "cropId": "",
    "totalConcurrentNumber": 0,
    "userConcurrentNumber": 0
  },
  "message": "",
  "success": true
}

Get app real-time sessions

Endpoint

/duix-openapi-v2/sdk/v2/getconcurrentList

Request Method: `GET`

Description Retrieve a list of all active (in-call) sessions for an app.

Parameters

Parameter Name	Type	Pass Method	Parameter Description
appId	String	Query	APPID created on the Duix platform

Close all sessions for an app

Endpoint

/duix-openapi-v2/sdk/v2/distroyCallSessionsByAppId

Request Method: `GET`

Description Terminate all active sessions for a specific app.

Parameters

Parameter Name	Type	Pass Method	Parameter Description
appId	String	Query	APPID created on the Duix platform

Example Response

{
  "code": "",
  "data": "",
  "message": "",
  "success": true
}

Close a specific session

Endpoint

/duix-openapi-v2/sdk/v2/sessionStop

Request Method: `GET`

Parameters

Parameter Name	Type	Pass Method	Parameter Description
uuid	String	Query	sessionId returned in the start-complete event

Third-Party Dialog Integration (Non-Streaming)

Integrate your own dialog system with Duix using a webhook-based POST approach.
The Duix platform will send user questions to your defined remote URL and expect a structured JSON response.

Example:
Refer to the open-source demo for a simple integration reference.

Request

The Duix platform sends each user question as a POST request to your remote endpoint using the format below.

Request Parameters

Field	Type	Description	Required
sid	String	User ID generated during account creation (visible in account info).	Y
dh-code	String	Digital human code, unique per digital human (viewable in the avatar overview).	Y
dh-question	String	The user’s question text.	Y
dh-conversation-id	String	Conversation ID — unique identifier for the session.	Y
dh-context	String	Conversation context, formatted as a stringified JSON object.	N
dh-context.q.context	String	Previous user question text (context).	N
dh-context.a.context	String	Previous digital human answer text (context).	N
uuid	String	Request ID used for tracking and troubleshooting.	N

Example Request

{
  "sid": "100003",
  "dh-code": "187265485019156480",
  "dh-question": "Who are you?",
  "dh-conversation-id": "0513e935-041f-48e0-9330-652ef4194511",
  "dh-context": [
    {
      "q": { "context": "user question" },
      "a": { "context": "answer" }
    }
  ]
}

Response: Reply using the format below.

Field	Type	Required	Description
code	String	Y	Response status code
msg	String	N	Optional success or error message
data	object	N	Data payload (see below)
success	Boolean	Y	Whether the request succeeded

Valid response codes

Code	Status	Response
200	OK	Successful response
400	Bad Request	Invalid body or headers
401	Unauthorized	Invalid authentication token
403	Forbidden	Authentication failed
500	Server Error	Service exception

Response body

Field	Type	Description	Required
conversationId	String	Conversation ID (matches the dh-conversation-id in the request).	Y
question	String	The user’s question.	N
answer	String	The digital human’s response, as a stringified JSON object.	Y
errorMsg	String	Description of any exception or error	N

Example Response

{
  "code": "200",
  "msg": "SUCCESS",
  "success": true,
  "data": {
    "conversationId": "0513e935-041f-48e0-9330-652ef4194511",
    "question": "who are you?",
    "answer": {
      "answer": "Welcome to UneeQ, how can I help?"
    },
    "errorMsg": ""
  }
}

Expected response time: Digital human interactions are latency‑sensitive. 95% of requests should complete within 20 seconds. If the response exceeds 20s, a timeout is reported, but the digital human will continue processing and respond once available.

Third-Party Dialog Integration (Streaming)

In streaming mode, Duix delivers incremental responses to your remote endpoint in real time as the digital human speaks.
This allows you to display or process partial answers before the full response completes.

Example:
Refer to the open-source demo for a simple streaming integration example.

Request

The Duix platform sends each user question to your remote URL via an HTTP POST request in the following format.

Parameters

Field	Type	Description	Required
sid	String	User ID generated during user creation (visible in account information).	Y
dh-code	String	Digital human code, unique per digital human (viewable in the avatar overview).	Y
dh-question	String	The question text sent by the user.	Y
dh-conversation-id	String	Unique identifier for the conversation.	Y
dh-context	String	Conversation context as a stringified JSON object.	N
dh-context.q.context	String	Previous question text in the conversation context.	N
dh-context.a.context	String	Previous answer text in the conversation context.	N
uuid	String	Request ID for tracking and debugging purposes.	N

Example Request

{
  "sid": "100003",
  "dh-code": "187265485019156480",
  "dh-question": "Who are you?",
  "dh-conversation-id": "0513e935-041f-48e0-9330-652ef4194511",
  "dh-context": [
    {
      "q": { "context": "user question" },
      "a": { "context": "answer" }
    }
  ]
}



Response body

| Field  | Type   | Description | Required |
| ------ | ------ | ----------- | -------- |
| answer | String | Partial or complete answer returned by the digital human | Y        |
| isEnd  | boolean | Indicates whether the current response is the final one | Y        |

Example Response

```json
{
    "answer": "Let the Cowherd and Weaver Girl meet on the Milky Way.",
    "isEnd": false
}

Get Conversation Details

Retrieve detailed configuration and metadata for a specific conversation on the Duix platform.

Endpoint

/duix-openapi-v2/sdk/getConversationById?conversationId=[conversation_id]

Method

GET

Description

Query conversation details by providing the conversation ID obtained from the Duix platform.

Parameters

Name	Type	Location	Description
conversationId	String	Query	Unique conversation ID generated by the Duix platform

Response

Field	Type	Description
code	String	Response code
data	JSON	Main conversation data
detailDto	JSON	Conversation resource details (includes model, background, and TTS configuration)
detailDto.backgroundDto	JSON	Background resource details
detailDto.modelId	String	Model ID
detailDto.modelName	String	Model name
detailDto.modelIdType	String	Model type (0 = Cloud Digital Human, 1 = Local Digital Human)
detailDto.localModelInfo	JSON	Local digital human information
detailDto.backgroundDto.backgroundUrl	String	Background image or video URL
scriptDtoList	JSON	Predefined dialog scripts
scriptDtoList.scriptType	String	Script type (0: Wake-up Word, 1: Opening Line, 2: Waiting Phrase, 3: Unknown Question, 4: Farewell, 5: Interruption, 6: Interruption Sentence, 7: Guiding Phrase)
scriptDtoList.scriptContent	String	Script text
scriptDtoList.ttsContent	String	Script audio file URL
message	String	Text message returned by the API
success	Boolean	Request success flag

Example Response

{
	"success": true,
	"code": "0",
	"message": "SUCCESS",
	"msg": "SUCCESS",
	"data": {
		"id": "108",
		"conversationName": "Unnamed-18:04",
		"language": "zh",
		"corpId": "1003645",
		"userId": "3959",
		"conversationConfigDto": null,
		"maxConversation": 2,
		"dataModelIsUsed": 1,
		"knowledgeIsUsed": 1,
		"fileIsUsed": 0,
		"thirdIsUsed": 0,
		"isFreedom": 0,
		"asrProvider": null,
		"conversationInfoDto": {
			"id": 109,
			"name": "1",
			"nickName": "",
			"gender": 1,
			"age": 0,
			"height": 0,
			"weight": 0,
			"characters": "",
			"backStory": ""
		},
		"detailDto": {
			"id": 95,
			"conversationId": "108",
			"proportion": "16:9",
			"terminalType": 0,
			"modelId": "321486924406853",
			"modelIdType": 0,
			"imageId": null,
			"sceneId": null,
			"modelName": "Model name",
			"sceneType": 0,
			"background": 1,
			"backgroundDto": {
				"id": 1,
				"backgroundCode": "1591003727513522176",
				"backgroundName": "zuoyi.jpg",
				"backgroundUrl": "/video-server/jpg/1592809647136509954.jpg",
				"fileType": 0,
				"proportion": "16:9",
				"userId": null
			},
			"modelConfig": null,
			"ttsId": "15",
			"ttsName": "guina",
			"ttsConfig": null,
			"ttsUrl": "",
			"ttsVolume": 0,
			"ttsSpeaker": "zhifeng_emo",
			"ttsSpeedRate": 0,
			"ttsPitch": 0,
			"ttsSource": 20,
			"samplePictureUrl": "/model/2023/02/06/c5348a17fac75feb0152a0c599b7af87.png",
			"videoWidth": 1920,
			"videoHeight": 1920,
			"humanProportion": "9:16",
			"humanWidth": 540,
			"humanHeight": 960,
			"humanX": 690,
			"humanY": 120,
			"localModelInfo": null
		},
		"knowledgeDtoList": [],
		"kbConversationDto": null,
		"modelDtoList": [
			{
				"id": 487,
				"conversationId": "108",
				"largeModelType": 0,
				"modelCode": 0,
				"largeName": "chatbot_law",
				"modelId": "1",
				"prompt": "Task: Your name is Zhang San, a real celebrity with a mischievous tone, humor, and a love for joking. Chatting with fans and friends, generating content replies in an oral style. \Requirements for generation: 1. Use my own name, 2. Meet the persona, 3. Prohibit the generation of English content, all must be generated in Chinese. 4. Within 30 words.",
				"botUrl": ""
			}
		],
		"thirdDto": null,
		"scriptDtoList": [
			{
				"id": 2728,
				"conversationId": "108",
				"scriptType": 0,
				"scriptContent": "Els silvrants",
				"ttsContent": null,
				"emotion": "0"
			},
			{
				"id": 2729,
				"conversationId": "108",
				"scriptType": 1,
				"scriptContent": "Hello, welcome to Duix",
				"ttsContent": "https://digital-public-dev.obs.cn-east-3.myhuaweicloud.com/tts-proxy/2024-02-20/1800-_-633043663081836544--FC34641E6EB0A22404C845E219904E81.wav",
				"emotion": "0"
			},
			{
				"id": 2730,
				"conversationId": "108",
				"scriptType": 2,
				"scriptContent": "Wait a moment, I'll think about it",
				"ttsContent": "https://digital-public-dev.obs.cn-east-3.myhuaweicloud.com/tts-proxy/2024-02-20/1630-_-633043667485855744--3F501A3CA51F4DFAFBACE254DD2E3E32.wav",
				"emotion": "0"
			},
			{
				"id": 2731,
				"conversationId": "108",
				"scriptType": 3,
				"scriptContent": "Sorry, I don't quite understand what you mean",
				"ttsContent": "https://digital-public-dev.obs.cn-east-3.myhuaweicloud.com/tts-proxy/2024-02-20/2300-_-633043669830471680--2C5A656A6FBEA2CE09037F21F3DF8434.wav",
				"emotion": "0"
			},
			{
				"id": 2732,
				"conversationId": "108",
				"scriptType": 4,
				"scriptContent": "Sorry, I don't quite understand what you mean",
				"ttsContent": "https://digital-public-dev.obs.cn-east-3.myhuaweicloud.com/tts-proxy/2024-02-20/560-_-633043672326082560--051995577E5C4B5818F952C04A7997E2.wav",
				"emotion": "0"
			},
			{
				"id": 2733,
				"conversationId": "108",
				"scriptType": 5,
				"scriptContent": "Stop talking",
				"ttsContent": null,
				"emotion": "0"
			},
			{
				"id": 2734,
				"conversationId": "108",
				"scriptType": 6,
				"scriptContent": "Okay, you can speak first",
				"ttsContent": "https://digital-public-dev.obs.cn-east-3.myhuaweicloud.com/tts-proxy/2024-02-20/1600-_-633043674196742144--FC70FD95B50E8CEC9D9151905AE13F7F.wav",
				"emotion": "0"
			},
			{
				"id": 2735,
				"conversationId": "108",
				"scriptType": 7,
				"scriptContent": "What is a digital person",
				"ttsContent": "https://digital-public-dev.obs.cn-east-3.myhuaweicloud.com/tts-proxy/2024-02-20/1080-_-633043676541358080--414A4CBCE8B52677F05DAECFD1437BD0.wav",
				"emotion": "0"
			}
		]
	}
}

Create Avatar

Create an AI avatar

Endpoint

/duix-openapi-v2/sdk/v2/createAvatar

Method

POST

Description

This endpoint create an AI avatar.

Parameters

Name	Type	Location	Description	Required
ttsName	String	Body	TTS name, select the public TTS voice. See at Settings -> Avatar creator -> Select voice	Y
conversationId	String	Body	The conversation ID. Value is required when using public AI avatar Get Conversation ID	N
coverImage	String	Body	A value is needed if you are using images to customize your AI avatar. Base64 format, example：data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA…	N
defaultSpeakingLanguage	String	Body	Default speaking language. default English	N
greetings	String	Body	Enter a greeting for your AI avatar’s first words, If not, the system will generate it randomly	N
name	String	Body	The name of AI avatar. If not, the system will generate it randomly	N
profile	String	Body	Enter a description of personality and preferences you’d love your AI avatar to have.. If not, the system will generate it randomly	N

Response

Field	Type	Description
code	String	Response code.
msg	String	Response message.
success	Boolean	Indicates whether the request succeeded.
data	JSON	Response payload containing avatar details.
data.taskId	String	The task ID of create AI avatar.

Example Response

{
  "code": "0",
  "msg": "SUCCESS",
  "success": true,
  "data": {
      "taskId": "00000184-1934-0eef-2f5e-c58ab9e3406c"
  }
}

Query Avatar

Retrieve information about the creation of an AI avatar using its unique taskId.

Endpoint

/duix-openapi-v2/sdk/v2/queryAvatar

Method

GET

Description

This endpoint returns metadata and training status for an AI avatar previously created through the API.

Parameters

Name	Type	Location	Description	Required
taskId	Integer	Query	Unique task ID returned by the `createAvatar` API.	Y

Response

Field	Type	Description
code	String	Response code.
msg	String	Response message.
success	Boolean	Indicates whether the request succeeded.
data	JSON	Response payload containing avatar details.
data.name	String	Avatar name.
data.modelSceneId	String	The avatar model scene ID.
data.conversationId	String	Conversation ID associated with this avatar.
data.coverImage	String	The avatar cover image
data.status	Integer	Avatar training status (`0`: training, `1`: failed, `2`: success).
data.processingStep	String	Training progress(preparing, processing, after_processing, done)

Example Response

{
  "code": "0",
  "msg": "SUCCESS",
  "success": true,
  "data": {
      "name": "Khalid Hassan",
      "modelSceneId": "735917732520006",
      "conversationId": "1983775419508027393",
      "coverImage": "https://xxx.xxx.xxx/image/img_3076d14.png",
      "status": 2,
      "processingStep": "done"
  }
}

API Documentation

iOS SDK

Android SDK

H5 SDK

​OpenAPI Integration

​1. Prerequisites

​Generate Signature and Obtain Token

​2. Management Interfaces

​Interaction Flow

​2.1 Get App Real-Time Concurrency

​Parameters

​Response

​Example Response

​Get app real-time sessions

Endpoint

Request Method: GET

Parameters

​Close all sessions for an app

Endpoint

Request Method: GET

Parameters

Example Response

​Close a specific session

Endpoint

Request Method: GET

Parameters

​Third-Party Dialog Integration (Non-Streaming)

​Request

Request Parameters

Example Request

​Third-Party Dialog Integration (Streaming)

​Request

Parameters

Example Request

​Get Conversation Details

​Endpoint

​Method

​Description

​Parameters

​Response

​Example Response

​Create Avatar

​Endpoint

​Method

​Description

​Parameters

​Response

​Example Response

​Query Avatar

​Endpoint

​Method

​Description

​Parameters

​Response

​Example Response

OpenAPI Integration

1. Prerequisites

Generate Signature and Obtain Token

2. Management Interfaces

Interaction Flow

2.1 Get App Real-Time Concurrency

Parameters

Response

Example Response

Get app real-time sessions

Request Method: `GET`

Close all sessions for an app

Request Method: `GET`

Close a specific session

Request Method: `GET`

Third-Party Dialog Integration (Non-Streaming)

Request

Third-Party Dialog Integration (Streaming)

Request

Get Conversation Details

Endpoint

Method

Description

Parameters

Response

Example Response

Create Avatar

Endpoint

Method

Description

Parameters

Response

Example Response

Query Avatar

Endpoint

Method

Description

Parameters

Response

Example Response