帮助与文档 > 产品文档 > AIGC > API文档 > AI口语老师
AI口语老师

AI口语老师简介

概念解释

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

说明

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

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

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

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

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

客服QQ:1906538062

AIGC产品技术交流群 :837394306

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

温馨提示:

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

协议须知

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

规则描述
传输方式HTTPS
请求方式POST
字符编码统一使用UTF-8 编码
请求格式JSON
响应格式JSON

接口调用参数

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表示完成主要任务和全部子任务
    }
  }
}       

错误代码列表

状态码状态码含义
101缺少必填的参数,首先确保必填参数齐全,然后,确认参数书写是否正确。
102不支持的语言类型
103翻译文本过长
104不支持的API类型
105不支持的签名类型
106不支持的响应类型
107不支持的传输加密类型
108应用ID无效,注册账号,登录后台创建应用并完成绑定,可获得应用ID和应用密钥等信息
109batchLog格式不正确
110无相关服务的有效应用,应用没有绑定服务。注:某些服务的结果发音需要tts服务,需要在控制台创建语音合成实例绑定应用后方能使用。
111开发者账号无效
112请求服务无效
113q不能为空
114不支持的图片传输方式
201解密失败,可能为DES,BASE64,URLDecode的错误
202签名检验失败,如果确认应用ID和应用密钥的正确性,仍返回202,一般是编码问题。请确保翻译文本 q 为UTF-8编码.
203访问IP地址不在可访问IP列表
205请求的接口与应用的平台类型不一致,确保接入方式(Android SDK、IOS SDK、API)与创建的应用平台类型一致。如有疑问请参考入门指南
206因为时间戳无效导致签名校验失败
207重放请求
303服务异常
405鉴权失败
AIDIALOG001topic字段长度或单词数超出限制
AIDIALOG002q字段长度超出限制
AIDIALOG003不支持的userLevel字段
AIDIALOG004不支持的count字段
AIDIALOG005indexArr字段取值无效
AIDIALOG006不支持的speaker字段
AIDIALOG007讲话人顺序异常
AIDIALOG008不支持的语种
AIDIALOG009content字段长度或单词数超出限制
AIDIALOG010生成场景接口请求失败
AIDIALOG011生成推荐表达接口请求失败
AIDIALOG012生成对话接口请求失败
AIDIALOG013history字段异常: 结构异常、超出对话轮次限制,生成报告接口该字段为空等。
AIDIALOG018基础服务异常
AIDIALOG019请求中包含敏感词
AIDIALOG020系统回话中包含敏感词
AIDIALOG021总字符数超出限制
AIDIALOG022系统无结果
AIDIALOG023scene字段异常
AIDIALOG024不支持的bot取值(scene中的字段)

常用语言 Demo

Java 示例

口语老师 Java demo

python3 示例

口语老师 python demo

go 示例

口语老师 go demo