实时对话数字人api接口开发文档

数字人实时对话api接口地址：https://api.kuhuyun.com/doc/41

 一、先搞懂：这个接口是干嘛的？

简单说，这是个“控制数字人”的工具。通过它，你能让数字人做4件核心事：

1. 创建任务（type=start）：启动一个数字人实例，相当于“叫醒数字人”。

2. 查询状态（type=status）：看看数字人现在是醒着（在线）、睡着（离线）还是正在醒（启动中）。

3. 开始对话（type=chat）：让数字人说指定的话，比如“你好，我是小虎”。

4. 释放任务（type=destroy）：用完数字人后“关掉它”，避免浪费资源。

 二、准备工作：调用接口前要凑齐3样东西

在“控制数字人”前，必须先拿到3个关键ID，就像开门需要3把钥匙：

| 关键信息 | 怎么拿到 | 作用 |

|----------|----------|------|

| 接口密钥（key） | 登录“ kuhuyun 控制台”，在“密钥管理”里找 | 证明你是合法用户，接口才会理你 |

| 数字人形象ID（avatar_id） | 通过“克隆API”生成 | 决定数字人长什么样（比如是小虎还是小美） |

| 数字人音色ID（voice_id） | 通过“克隆API”生成 | 决定数字人说话的声音（比如是男声还是女声） |

 三、实操步骤：分4种场景教你用

下面按“最常用的4个需求”拆解，每步都标清楚“要填什么”。

 场景1：启动数字人（创建任务，type=start）

这是第一步，先把数字人“叫醒”。

1. 请求方式：用“HTTP POST”（可以理解为“给接口发消息”的方式）。

2. 必须带的“消息头”（HEADER）：

   - 名称填“Content-Type”，值填“application/x-www-form-urlencoded;charset:utf-8;”

   - 作用：告诉接口，你发的内容是“表单格式”，且用中文编码（避免乱码）。

3. 必须传的参数（相当于给数字人的“指令”）：

   | 参数名 | 要不要填 | 填什么 | 示例 |

   |--------|----------|--------|------|

   | key | 必须 | 你的接口密钥 | 35kj5jnlj53453kl5j43nj5 |

   | type | 必须 | 填“start”（表示启动） | start |

   | avatar_id | 必须 | 你的数字人形象ID | 04456aae3f1348278351bee77bfe6343 |

   | voice_id | 必须 | 你的数字人音色ID | 04456aae3f1348278351bee77bfe6343 |

   | robot_id | 必须 | 数字人实例ID（如果是第一次启动，可能需要先获取，具体看平台说明） | 04456aae3f1348278351bee77bfe6343 |

 场景2：让数字人说话（开始对话，type=chat）

数字人启动后，用这个步骤让它开口。

1. 请求方式和HEADER：和“场景1”完全一样。

2. 额外要加的参数：

   - 除了场景1里的key、type（这里填“chat”）、avatar_id、voice_id、robot_id，还要加“text”参数。

   - text：填数字人要讲的话，建议每次不超过20字（最多100字）。

   - 示例：text=“你好！我是数字人小虎。”

 场景3：查数字人状态（type=status）

想知道数字人现在能不能用，就查这个。

1. 请求方式和HEADER：和“场景1”一样。

2. 参数：

   - type填“status”，其他参数（key、avatar_id、voice_id、robot_id）和场景1一样。

3. 看结果重点：返回里的“status”字段：

   - waiting：数字人还在启动，等一会儿再查。

   - online：数字人醒了，可以说话了。

   - offline：数字人没启动，需要重新执行“场景1”。

 场景4：关掉数字人（释放任务，type=destroy）

不用数字人了，一定要关，避免占资源。

1. 请求方式和HEADER：和“场景1”一样。

2. 参数：type填“destroy”，其他参数（key、avatar_id、voice_id、robot_id）和场景1一样。

 四、看结果：接口会给你什么反馈？

你给接口发完请求后，它会回一个“JSON格式”的消息，重点看3个地方：

1. code（状态码）：

   - 200：成功（比如数字人启动成功、说话成功）。

   - 非200：失败（比如密钥填错了、参数没给全，具体看“msg”）。

2. msg（状态信息）：

   - 成功会显示“success”，失败会告诉你原因（比如“key错误”“缺少avatar_id”）。

3. data（核心结果）：

   - 启动成功（start）：会有“pull_url”，这是数字人实例的链接，用来后续对接（比如在网页上显示数字人）。

   - 查状态（status）：会有“status”字段，告诉你数字人当前状态（online/offline/waiting）。

 五、小白福利：直接用现成工具调试

不用自己写代码，用官方给的工具直接试：

1. 在线调试工具：打开链接 https://s.apifox.cn/84c7b928-f4fc-4ea3-b324-efe362baa23c/367936279e0

2. 操作步骤：

   - 选择“请求方式”为POST，填好接口地址（https://api.kuhuyun.com/api/ai/imhuman）。

   - 在“HEADER”里加好Content-Type参数。

   - 在“表单参数”里填好key、type、各个ID，点“发送”就能看到结果。

3. 看效果：想先体验数字人说话，打开demo链接 https://api.kuhuyun.com/1/demoimhuman.html ，直观感受功能。

来源：酷虎云api平台