AI口语老师简介

概念解释

AI口语老师服务，可以根据用户的需求和偏好生成更加自然、流程和准确的对话内容，并根据用户对话给出高质量的自然语言评价，为用户提供更加个性化、贴心的对话体验。

说明

Hi，您好，欢迎使用有道智云AI口语老师接口服务。

本文档主要针对需要集成HTTP API的技术开发工程师，详细描述AI口语老师能力相关的技术内容。

如果您有与我们商务合作的需求，可以通过以下方式联系我们：

商务邮箱： AIcloud_Business@corp.youdao.com

如果您对文档内容有任何疑问，可以通过以下几种方式联系我们：

客服QQ：1906538062

AIGC产品技术交流群 ：837394306

联系邮箱： zhiyun@corp.youdao.com

温馨提示：

• 本文档主要针对开发人员，接入测试前需要获取应用ID和应用密钥，并创建应用；如果您还没有，请按照 新手指南 获取。
• 平台向每个账户赠送50元的体验金，供用户集成前测试所用。

协议须知

调用方在集成AI口语老师API时，请遵循以下规则。

接口调用参数

AI口语老师线上调用地址：

https://openapi.youdao.com/ai_dialog

服务配置说明

1、服务支持10轮对话，系统根据对话轮次，任务完成度，主动回复客户bye bye，并将end标志设置为结束。
2、如果对话已经结束，再请求生成对话或者推荐表达接口，系统可能只会返回 bye bye。
3、对话历史系统和用户content字段的总字符数限制：12000.
4、口语对话服务各接口统一设置 ：Content-Type ： application/json
5、生成签名时，q字段的取值在对应的接口里有说明。

注意：
签名生成方法如下：
signType=v3；
sign=sha256(应用ID+input+salt+curtime+应用密钥)；
其中，input的计算方式为：input=q前10个字符 + q长度 + q后10个字符（当q长度大于20）或 input=q字符串（当q长度小于等于20）；

AI口语老师接口定义

获取默认场景列表接口

• 接口uri：/get_default_topic

接口参数：

{
    "appKey":"",
    "salt":"",       // 随机值
    "curtime":"",    // 时间戳
    "signType":"v3", // 仅支持v3
    "sign":"",       // 生成方式见demo, q取q字段
    "q":"topics"     // 固定值
}

• 响应结果示例

{    
  "code": "0", //错误码   
  "msg": "SUCCESS", //信息说明    
  "data": {
    "topicList": [
      {
        "tag": "初级",
        "topics": [
          {
            "emoji": "😄",
            "name": "互相介绍",
            "enName": "Introduce yourself to a friend at school"
          }
        ]
      }
    ]
  }
}

场景生成接口

• 接口uri：/generate_topic
• 接口说明：
  用户提供简要话题，系统返回具体的场景信息。
• 接口参数：

{
  "appKey":"",
  "salt":"",       // 随机值
  "curtime":"",    // 时间戳
  "signType":"v3", // 仅支持v3
  "sign":"",       // 生成方式见demo，q取topic字段
  "topic": "Introduce yourself to a friend at school" // 用户指定的话题关键词，语种限制英文，长度限制 < 500，单词数限制 < 100
}

• 响应结果

{
  "code": "0",
  "msg": "SUCCESS",
  "data": {
    "taskId": "f52c2df42bc311ee9d19bebd871cbd01", // 任务id
    "scene": {
      "mainTask": "Introduce yourself and get to know your new friend", // 主任务：对话目标
      "emoji": "👋",
      "subTasks": [  // 子任务列表
        "1. Tell your friend your name and where you are from",
        "2. Ask your friend about her hobbies and interests",
        "3. Talk about your favorite subject in school",
        "4. Ask your friend if she has any advice for navigating the school"
      ],
      "botGender": "Female", // 系统性别, 取值范围： Male 男性； Female 女性；
      "botRole": "Friend",   // 系统角色
      "userRole": "New student",        // 用户角色
      "content": "First day of school"  // 场景内容
    }
  }
}

生成对话接口

• 接口uri：/generate_dialog
• 接口说明：
  用户和系统之间的对话接口。特别注意： 第一次需要把场景信息告诉系统,让系统生成第一句话；
• 接口参数：

{
    "appKey":"", 
    "salt":"",       // 随机值
    "curtime":"",    // 时间戳
    "signType":"v3", // 仅支持v3
    "sign":"",       // 生成方式见demo, q取taskId
    "taskId": "f52c2df42bc311ee9d19bebd871cbd01",  // 场景生成接口返回的任务id
    "scene": {  // 生成场景接口返回的 scene 字段
      "mainTask": "Introduce yourself and get to know your new friend",
      "emoji": "👋",
      "subTasks": [
        "1. Tell your friend your name and where you are from",
        "2. Ask your friend about her hobbies and interests",
        "3. Talk about your favorite subject in school",
        "4. Ask your friend if she has any advice for navigating the school"
      ],
      "botGender": "Female",
      "botRole": "Friend",
      "userRole": "New student",
      "content": "First day of school"
    },
    "userLevel": "0", // 用户等级：0表示1-3年级小学生；1表示4-6年级小学生；2表示初中学生；3表示高中学生；
    "history": [      // 对话历史，讲话人字段：系统与用户必须交替出现，第一句话的讲话人必须是系统，获取系统说的第一句话时，history传空数组
    ]
  }

• 响应结果

{
  "code": "0",
  "msg": "SUCCESS",
  "data": {
    "endCode": 0, //结束码：0-未结束； 1-结束；
    "taskId": "f52c2df42bc311ee9d19bebd871cbd01", // 任务id
    "resultArr": [
      {
        "result": [ // 系统回话
          "Hi there! My name is Sarah, and I'm from New York. What's your name and where are you from?"
        ],
        "score": 0, // 对话接口不关注此字段
        "achievement": [],  // 对话接口不关注此字段
        "index": -1  // 对话接口不关注此字段
      }
    ]
  }
}

生成推荐表达接口

• 接口uri：/generate_recommendation
• 接口说明：
  用户提供场景信息和对话历史，并指定要系统推荐表达的句子，系统会根据场景信息和对话上下文返回推荐的 1 - 3 句表达例句。
• 接口参数：

{
    "appKey":"", 
    "salt":"",       // 随机值
    "curtime":"",    // 时间戳
    "signType":"v3", // 仅支持v3
    "sign":"",       // 生成方式见demo, q取taskId
    "taskId": "f52c2df42bc311ee9d19bebd871cbd01",  // 场景生成接口返回的任务id
    "scene": {  // 生成场景接口返回的 scene 字段
      "mainTask": "Introduce yourself and get to know your new friend",
      "emoji": "👋",
      "subTasks": [
        "1. Tell your friend your name and where you are from",
        "2. Ask your friend about her hobbies and interests",
        "3. Talk about your favorite subject in school",
        "4. Ask your friend if she has any advice for navigating the school"
      ],
      "botGender": "Female",
      "botRole": "Friend",
      "userRole": "New student",
      "content": "First day of school"
    },
    "userLevel": "0", // 用户等级：0表示1-3年级小学生；1表示4-6年级小学生；2表示初中学生；3表示高中学生；
    "history": [      // 对话历史，讲话人字段：系统与用户必须交替出现
       {
          "speaker":"System",  // 讲话人：系统，第一句话的讲话人必须是系统
          "content":"Hi there! My name is Sarah, and I'm from New York. What's your name and where are you from?"  // 讲话内容, 语种限制英文
       },
       {
           "speaker":"User",   // 讲话人：用户
           "content":"Hello, I'm Echo, I come from China. Nice to meet you. Do you have any hobbies?" // 讲话内容, 语种限制英文，单词数限制80
       }
    ],
    "indexArr": [ // 请求系统生成推荐表达例句的索引（对应history数组），取值为 0 - history.length, 如果取值 = history.length,则会生成对话历史的下一句话, 目前该数组中仅支持一个值
        "1"
    ],
    "count": "1" // 系统生成推荐表达例句的数量，取值 1 - 3，存在指定为3但结果不足3句的情况
  }

• 响应结果

{
  "code": "0",
  "msg": "SUCCESS",
  "data": {
    "endCode": 0, //结束码：0-未结束； 1-结束；
    "taskId": "f52c2df42bc311ee9d19bebd871cbd01",  // 任务id
    "resultArr": [
      {
        "result": [ // 系统生成的推荐表达例句
          "Hi Sarah, my name is Echo, and I'm from China."
        ],
        "score": 0, // 生成推荐接口不关注此字段
        "achievement": [], // 生成推荐接口不关注此字段
        "index": 0 // 用户指定的会话历史中的索引
      }
    ]
  }
}

生成报告接口

• 接口uri：/generate_report
• 接口说明：
  用户提供场景信息和对话历史，系统生成报告，报告包含语法评价、句子润色、语音评价、任务完成度评价。
• 接口参数：

{
    "appKey":"", 
    "salt":"",       // 随机值
    "curtime":"",    // 时间戳
    "signType":"v3", // 仅支持v3
    "sign":"",       // 生成方式见demo, q取taskId
    "taskId": "f52c2df42bc311ee9d19bebd871cbd01",  // 场景生成接口返回的任务id
    "scene": {  // 生成场景接口返回的 scene 字段
      "mainTask": "Introduce yourself and get to know your new friend",
      "emoji": "👋",
      "subTasks": [
        "1. Tell your friend your name and where you are from",
        "2. Ask your friend about her hobbies and interests",
        "3. Talk about your favorite subject in school",
        "4. Ask your friend if she has any advice for navigating the school"
      ],
      "botGender": "Female",
      "botRole": "Friend",
      "userRole": "New student",
      "content": "First day of school"
    },
    "userLevel": "0", // 用户等级：0表示1-3年级小学生；1表示4-6年级小学生；2表示初中学生；3表示高中学生；
    "history": [      // 对话历史，讲话人字段：系统与用户必须交替出现
       {
          "speaker":"System",  // 讲话人：系统，第一句话的讲话人必须是系统
          "content":"Hi there! My name is Sarah, and I'm from New York. What's your name and where are you from?"  // 讲话内容, 语种限制英文
       },
       {
           "speaker":"User",   // 讲话人：用户
           "content":"Hello, I'm Echo, I come from China. Nice to meet you. Do you have any hobbies?" // 讲话内容, 语种限制英文，单词数限制80
           "voice":"" // 选填字段：音频的base64编码， 如果不填，会影响最终的语音评分。音频格式要求：采样率16K，单声道，wav，如格式不符，会影响评分结果。
       },
       {
          "speaker":"System",
          "content":"Yes, I love hiking and playing tennis. What about you?"
       },
       {
          "speaker":"User",
          "content":"I like singing and running, especially listening to music while running. It's one of my favorite ways to relax. I also like listening to music while reading, so I like Chinese class, how about you?"
       }
    ]
  }

• 响应结果

{
  "code": "0",
  "msg": "SUCCESS",
  "data": {
    "history": [  // 会话历史， 仅评价用户的讲话内容
      {
        "index": "1", 
        "speaker": "User",
        "content": "Hello, I'm Echo, I come from China. Nice to meet you. Do you have any hobbies?",
        "needImprove": "false",  // 是否需要改进:true 表示需要； false 表示不需要
        "paraphrase": null,  // 润色结果，如果content的长度 <30 或者单词数 <3,会导致无法生成润色结果。 
        "suggest": {  // 系统建议
          "grammar": null,  // 语法评价
          "voice": {        // 语音评价
            "overall": "0.000040",  // 发音得分
            "words": [
              {
                "word": "Hello",
                "text": "Hello 发音不清晰, 其中 h、e 发音不准确"
              },
              {
                "word": "I'm",
                "text": "I'm 发音不清晰, 其中 aɪ、m 发音不准确"
              }
            ]
          }
        }
      },
      {
        "index": "3",
        "speaker": "User",
        "content": "I like singing and running, especially listening to music while running. It's one of my favorite ways to relax. I also like listening to music while reading, so I like Chinese class, how about you?",
        "needImprove": "true",
        "paraphrase": [
          {
            "rawSent": "I like singing and running, especially listening to music while running.", // 原句
            "diffs": [  // 操作
              {
                "text": "I",
                "operation": "EQUAL" // 不变
              },
              {
                "text": "like",
                "operation": "DELETE"  // 删除
              },
              {
                "text": "love",
                "operation": "INSERT"  // 插入
              },
              {
                "text": "singing and running, especially listening to music while running.",
                "operation": "EQUAL"  // 不变
              }
            ]
          },
          {
            "rawSent": "It's one of my favorite ways to relax.",
            "diffs": null
          },
          {
            "rawSent": "I also like listening to music while reading, so I like Chinese class, how about you?",
            "diffs": [
              {
                "text": "I also like",
                "operation": "EQUAL"
              },
              {
                "text": "listening",
                "operation": "DELETE"
              },
              {
                "text": "to listen",
                "operation": "INSERT"
              },
              {
                "text": "to music while reading, so I like Chinese",
                "operation": "EQUAL"
              },
              {
                "text": "class,",
                "operation": "DELETE"
              },
              {
                "text": "lessons,",
                "operation": "INSERT"
              },
              {
                "text": "how about you?",
                "operation": "EQUAL"
              }
            ]
          }
        ],
        "suggest": {
          "grammar": {
            "advice": "语法结构丰富，语言运用自然流畅，没有语法错误",
            "score": "79.7"
          },
          "voice": null
        }
      }
    ],
    "scene": { // 场景信息
      "emoji": "👋",
      "name": "First day of school"
    },
    "summary": {  // 报告概要
      "grammarScore": "64",  // 语法得分
      "voiceScore": "0",  // 音频得分
      "wordNum": "125",   // 单词数
      "star": "3"  // 任务完成评分，1表示完成主要任务，2表示完成主要任务和部分子任务，3表示完成主要任务和全部子任务
    }
  }
}       

错误代码列表

常用语言 Demo

Java 示例

口语老师 Java demo

python3 示例

口语老师 python demo

go 示例

口语老师 go demo