AI英语老师api接入文档说明

文档状态

文件标识：	TuringOS-AIteacher-V1.0
系统版本：	HTTP
作者：	蔡利伟
完成日期：	2023年10月18日

文档修订记录

文档版本号	修订日期	修订原因	修订人
V1.0	2023.10.18	创建文档	蔡利伟
V2.0	2023.10.24	新增主题对话回复、推荐回复、语法纠正、表达相关度接口	蔡利伟
V2.1	2023.11.09	新增表达润色能力接口	蔡利伟
V2.2	2023.11.10	增加章节&话题示例	蔡利伟
V2.3	2023.11.23	增加场景和话题获取接口	蔡利伟
V2.4	2023.11.30	入参grade取值范围改为1-12	蔡利伟
V2.5	2023.12.07	场景和话题获取接口增加支持初、高中内容	蔡利伟
V2.6	2023.12.27	新增模考相关度测评能力	蔡利伟
V2.7	2024.03.06	主题对话回复能力入参新增参数final	蔡利伟
V2.8	2024.05.09	年级新课标筛选入参和主题对话信息补充	李盼盼
V2.9	2024.05.09	新增主题对话看板信息生成功能	李盼盼
V3.0	2024.05.11	表达润色功能，新增非必传的grade入参	李盼盼
V3.1	2024.07.15	主题对话回复能力入参lastA支持中英混合	李盼盼
V3.2	2024.08.06	新增使用翻译技能说明	李盼盼

机器人类型必须为

SDK接入（Android）、 WebSocket接入、混合SDK接入（Android）、混合SDK接入（Linux）

1.请求域名

请求环境	请求域名
prod	http://nluskilll.turingos.cn

2.参数加密说明

加密模式 CBC
填充 PKCS5Padding
数据块 128位(密钥为16位)
输出 base64编码字符串
编码 utf-8
密钥 apikey+图灵官网机器人详情页Secret+当前毫秒时间戳(取输入参数)-->对该字符串取16位
小写md5值(参考 https://www.sojson.com/encrypt_md5.html)

注：偏移量字符串等于密钥

加密参考页面 http://tool.chacuo.net/cryptaes

加密内容为data字段，结构如下:

{
        "deviceId": "****",
        "params":
        {
        }
    }

3.AI英语老师接口

接口URI：/aigc/ability

请求方式：POST

参数格式：json

3.1 话题生成[requestCode=2204]

加密请求示例：

{
    "key": "****",
    "requestCode": 2204,
    "data":"pzvwkxZax5LgQ",
    "timestamp": 1505390837793
}

加密前请求示例：

{
    "key": "****",
    "requestCode": 2204,
    "data":
    {
        "deviceId": "****",
        "params":
        {
            "grade": 1,
            "scene": "测试",
            "topic": "测试"
        }
    },
    "timestamp": 1505390837793
}

输出示例

{
  "desc": "success",
  "code": 200,
  "globalId": 219447299425438000,
  "payload": {
    "chats": [
      {
        "teacher": "What stationery items do you have?",
        "student": "I have pencils, erasers, and rulers."
      },
      {
        "teacher": "Do you have a pencil sharpener?",
        "student": "No, I don't have a pencil sharpener."
      },
      {
        "teacher": "Where do you buy your stationery?",
        "student": "I buy my stationery from the school store."
      },
      {
        "teacher": "What color is your pencil case?",
        "student": "My pencil case is blue."
      },
      {
        "teacher": "Can I borrow your ruler?",
        "student": "Sure, you can borrow my ruler."
      }
    ]
  }
}

能力输入说明

参数	类型	是否必须	取值范围	说明
grade	int	Y	1-12	年级
topic	String	Y	-	话题内容，最多7个汉字
scene	String	N	-	场景内容，最多4个汉字

能力输出说明(chats->array)

参数	类型	是否必须	取值范围	说明
teacher	String	Y	-	对话内容
student	String	Y	-	对话内容

3.2主题对话回复[requestCode=2200]

加密请求示例：

{
    "key": "****",
    "requestCode": 2200,
    "data":"pzvwkxZax5LgQ",
    "timestamp": 1505390837793
}

加密前请求示例：

{
    "key": "****",
    "requestCode": 2200,
    "data":
    {
        "deviceId": "***",
        "params":
        {
            "grade": 1,
            "scene": "测试",
            "lastA": "hllo,aa",
            "lastQ": "hello",
            "topic": "测试"
        }
    },
    "timestamp": 1505390837793
}

输出示例

{
    "desc": "success",
    "code": 200,
    "globalId": null,
    "payload": {
        "reply": "Oh, that's great! What else do you have in your pencil case?"
    }
}

能力输入说明

参数	类型	是否必须	取值范围	说明
grade	int	Y	1-12	年级
scene	String	N	-	场景内容，最多4个汉字
topic	String	Y	-	话题内容，最多7个汉字
lastA	String	N	中文/英文/中英混合输入	必须和lastQ同时存在或不存在
lastQ	String	N	英文输入	必须和lastA同时存在或不存在
final	String	N	取值：最后一轮	是否是最后一轮，固定传参文本，传入则为结束句对话生成

能力输出说明

参数	类型	是否必须	取值范围	说明
reply	String	Y	-	主题对话回复

注：lastA和lastQ不存在时，即不存在上下文，可用于对话首句的生成使用。
注：当final传参时，即对话最后一轮，需要传lastA和lastQ，否则大模型无法生成最后一轮结束语对话。
注：带对话场景scene+话题topic的入参，适合限制对话轮数（五轮）。只带有话题topic的入参，适合围绕话题的开放域对话（可不限制对话轮数）。

3.3推荐回复[requestCode=2201]

加密请求示例：

{
    "key": "****",
    "requestCode": 2201,
    "data":"pzvwkxZax5LgQ",
    "timestamp": 1505390837793
}

加密前请求示例：

{
    "key": "****",
    "requestCode": 2201,
    "data":
    {
        "deviceId": "***",
        "params":
        {
            "grade": 1,
            "currQ": "hello"
        }
    },
    "timestamp": 1505390837793
}

输出示例

{
    "desc": "success",
    "code": 200,
    "globalId": null,
    "payload": {
        "recommend": [
            "1. Here is my pencil.",
            "2. I have a pen.",
            "3. Yes, I have a ruler."
        ]
    }
}

能力输入说明

参数	类型	是否必须	取值范围	说明
grade	int	Y	1-12	年级
currQ	String	Y	英文输入	本轮对话

能力输出说明

参数	类型	是否必须	取值范围	说明
recommend	array	Y	-	推荐回复

3.4语法纠正[requestCode=2202]

加密请求示例：

{
    "key": "****",
    "requestCode": 2202,
    "data":"pzvwkxZax5LgQ",
    "timestamp": 1505390837793
}

加密前请求示例：

{
    "key": "*****",
    "requestCode": 2202,
    "data":
    {
        "deviceId": "***",
        "params":
        {
            "currA": "hello"
        }
    },
    "timestamp": 1505390837793
}

输出示例

{
    "desc": "success",
    "code": 200,
    "globalId": null,
    "payload": {
        "result": true,
        "knowledge": "这句话没有语法错误。"
    }
}

能力输入说明

参数	类型	是否必须	取值范围	说明
currA	String	Y	英文输入	本轮用户的对话

能力输出说明

参数	类型	是否必须	取值范围	说明
result	boolean	Y	-	是否有语法错误；true为没语法问题，false为有语法问题
knowledge	String	N	-	相关语法讲解，纠正后的英文句子

3.5表达相关度[requestCode=2203]

加密请求示例：

{
    "key": "****",
    "requestCode": 2203,
    "data":"pzvwkxZax5LgQ",
    "timestamp": 1505390837793
}

加密前请求示例：

{
    "key": "****",
    "requestCode": 2203,
    "data":
    {
        "deviceId": "***",
        "params":
        {
            "currA": "hello",
            "currQ": "hello"
        }
    },
    "timestamp": 1505390837793
}

输出示例

{
    "desc": "success",
    "code": 200,
    "globalId": null,
    "payload": {
        "score": 80,
        "message": "回答符合语境，学生有铅笔，可以展示给老师看"
    }
}

能力输入说明

参数	类型	是否必须	取值范围	说明
currA	String	Y	英文输入	本轮用户的对话
currQ	String	Y	英文输入	本轮机器人的对话

能力输出说明

参数	类型	是否必须	取值范围	说明
score	int	Y	-	表达相关度得分
message	String	N	-	错误分析

3.6表达润色[requestCode=2206]

加密请求示例：

{
    "key": "****",
    "requestCode": 2206,
    "data":"pzvwkxZax5LgQ",
    "timestamp": 1505390837793
}

加密前请求示例：

{
  "key": "*****",
  "requestCode": 2206,
  "data":
  {
    "deviceId": "*****",
    "params":
    {
      "grade": 1,
      "lastA": "hello"
    }
  },
  "timestamp": 1505390837793
}

输出示例

{
  "desc": "success",
  "code": 200,
  "globalId": 221329486686492000,
  "payload": {
    "express": "Greetings"
  }
}

能力输入说明

参数	类型	是否必须	取值范围	说明
grade	int	N	1-12	年级
lastA	String	Y	限英文	用户的回答文本

能力输出说明

参数	类型	是否必须	取值范围	说明
express	String	Y	-	润色后内容

3.7模考相关度[requestCode=2212]

加密请求示例：

{
    "key": "****",
    "requestCode": 2212,
    "data":"pzvwkxZax5LgQ",
    "timestamp": 1505390837793
}

加密前请求示例：

{
  "key": "*****",
  "requestCode": 2212,
  "data":
  {
    "deviceId": "*****",
    "params":
    {
      "stanA": "I  want to go to hangzhou.",
      "currA": "I want to go to Beijing"
    }
  },
  "timestamp": 1505390837793
}

输出示例

{
  "desc": "success",
  "code": 200,
  "globalId": 221329486686492000,
  "payload": {
    "score": 60
  }
}

能力输入说明

参数	类型	是否必须	取值范围	说明
stanA	String	Y	限英文	标准答案
currA	String	Y	限英文	用户回答

能力输出说明

参数	类型	是否必须	取值范围	说明
score	int	Y	0-100	分数

3.8主题任务看板信息生成[requestCode=2220]

加密请求示例：

{
    "key": "****",
    "requestCode": 2220,
    "data":"pzvwkxZax5LgQ",
    "timestamp": 1505390837793
}

加密前请求示例：

{
    "key": "****",
    "requestCode": 2220,
    "data":
    {
        "deviceId": "***",
        "params":
        {
            "identity": "小学",
            "topic": "我的文具"
        }
    },
    "timestamp": 1505390837793
}

输出示例

{
    "desc": "success",
    "code": 200,
    "globalId": null,
    "payload": {
        "task": "讨论各自最喜欢的文具",
        "where": "小学教室",
        "who": "小明和小红"
    }
}

能力输入说明

参数	类型	是否必须	取值范围	说明
identity	String	Y	小学初中高中	学段年级
topic	String	Y	-	话题内容，最多7个汉字

能力输出说明

参数	类型	是否必须	取值范围	说明
where	String	Y	-	对话场景的描述
who	String	Y	-	对话中扮演的角色
task	String	Y	-	对话任务的详细描述

注：如需使用翻译功能，由于翻译技能1000018有150字符限制，建议开通全文翻译技能50102，具体开通信息请联系商务人员。

4.返回code

code	说明
200	正确返回
-1	未知错误，查看desc信息
44001	非法requestCode请求
44002	请求参数错误，查看desc信息
44003	大模型超时，请重试
44004	请求缺失requestCode
44005	大模型输出参数错误，查看desc信息
44006	参数解密失败
44007	入参为空，未加密apikey不能使用data入参!
44008	PROMPT EMPTY,参数错误，请检查
44009	大模型请求失败（注意apikey是否授权ChatGPT）
44010	大模型返回json错误（返回中有具体大模型返回内容）

5.附件

5.1提供英语口语老师C版里大模型预生成话题和章节结构数据供参考

英语口语老师C版-章节&话题示例-点击下载

6.场景和话题数据获取接口

6.1 根据年级查看场景

请求URL

/aigc/chapter/queryTheme

请求方式

POST

加密请求示例

{
  "key": "dse34xsw3*****dsdfd",
  "data": "PWCC1ZEcU+gClGWqqB6o6C0gbPU08YNqmzeiceLVUGnqwpPTlTyvhwevF22GMqNl8bYFrXfsFG5aOHZB3b9Y1g==",
  "timestamp": "1788242124123"
}

data示例

 {
  "deviceId": "ai123341",
  "params": {
    "grade": "一年级"
  }
}

参数

参数名	必选	类型	说明
grade	否	string	年级，可取的值：一年级二年级....六年级；初一、初二、初三；高一、高二、高三，不填则全部返回；按新课标筛选，则传入：多个年级值，多个年级用英文逗号隔开。
key	是	string	apikey
deviceId	是	string	设备id
data	是	string	加密后的数据
timestamp	是	string	时间戳 13位毫秒

返回示例

{
    "code": 200,
    "msg": "success",
    "datas": [
        {
            "chapterId": 1,
            "chapterName": "校园生活",
            "chapterNameEn": "campus life",
            "chapterPic": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/english/cover/scene1.png",
            "topicTotal": [
                {
                    "grade": "一年级",
                    "gradeId": 1,
                    "total": 2
                }
            ]
        },
        {
            "chapterId": 4,
            "chapterName": "兴趣爱好",
            "chapterNameEn": null,
            "chapterPic": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/english/cover/scene4.png",
            "topicTotal": [
                {
                    "grade": "一年级",
                    "gradeId": 1,
                    "total": 3
                }
            ]
        },
        {
            "chapterId": 6,
            "chapterName": "温暖的家",
            "chapterNameEn": null,
            "chapterPic": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/english/cover/scene6.png",
            "topicTotal": [
                {
                    "grade": "一年级",
                    "gradeId": 1,
                    "total": 1
                }
            ]
        },
        {
            "chapterId": 7,
            "chapterName": "动植物",
            "chapterNameEn": null,
            "chapterPic": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/english/cover/scene7.png",
            "topicTotal": [
                {
                    "grade": "一年级",
                    "gradeId": 1,
                    "total": 2
                }
            ]
        },
        {
            "chapterId": 8,
            "chapterName": "讨论美食",
            "chapterNameEn": null,
            "chapterPic": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/english/cover/scene8.png",
            "topicTotal": [
                {
                    "grade": "一年级",
                    "gradeId": 1,
                    "total": 3
                }
            ]
        },
        {
            "chapterId": 11,
            "chapterName": "身体五官",
            "chapterNameEn": null,
            "chapterPic": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/english/cover/scene11.png",
            "topicTotal": [
                {
                    "grade": "一年级",
                    "gradeId": 1,
                    "total": 1
                }
            ]
        }
    ]
}

返回参数说明

参数名	类型	说明
chapterId	int	场景id
chapterName	String	场景名字
chapterNameEn	String	场景英文名字
chapterPic	String	场景封面
topicTotal	Array	话题信息
grade	String	对应支持的年级（可能为多个）
gradeId	int	年级ID
total	int	场景里话题总个数

6.2 根据场景id和年级获取话题

请求URL

/aigc/chapter/queryTopicByTheme

请求方式

POST

加密请求示例

{
  "key": "dse34xsw3*****dsdfd",
  "data": "PWCC1ZEcU+gClGWqqB6o6C0gbPU08YNqmzeiceLVUGnqwpPTlTyvhwevF22GMqNl8bYFrXfsFG5aOHZB3b9Y1g==",
  "timestamp": "1788242124123"
}

data示例

 {
  "deviceId": "ai123341",
  "params": {
    "chapterId": 1,
    "grade": "一年级"
  }
}

参数

参数名	必选	类型	说明
grade	否	string	年级，可取的值：一年级二年级....六年级；初一、初二、初三；高一、高二、高三，不填则全部返回；按新课标筛选，则传入：多个年级值，多个年级用英文逗号隔开。
chapterId	是	string	场景id
key	是	string	apikey
deviceId	是	string	设备id
data	是	string	加密后的数据
timestamp	是	string	时间戳 13位毫秒

返回示例

{
  "code": 200,
  "msg": "success",
  "datas": [
    {
      "chapterId": 1,
      "topicId": 1,
      "topic": "我的文具",
      "grade": "一年级",
      "gradeId": 1
    },
    {
      "chapterId": 1,
      "topicId": 2,
      "topic": "教室物品",
      "grade": "一年级",
      "gradeId": 1
    }
  ]
}

返回参数说明

参数名	类型	说明
chapterId	int	场景id
grade	String	年级
gradeId	int	年级id
topic	String	话题
topicId	int	话题id

注：新课标筛选范围如下：Lv0: 对应一到二年级；Lv1: 对应三到四年级；Lv2: 对应五到六年级；Lv3: 对应初一到初三。按新课标筛选时，入参为多个年级，多个年级用英文逗号隔开。

6.3 获取话题详情

请求URL

/aigc/chapter/queryTopicDetail

请求方式

POST

请求示例

{
  "key": "dse34xsw3*****dsdfd",
  "data": "PWCC1ZEcU+gClGWqqB6o6C0gbPU08YNqmzeiceLVUGnqwpPTlTyvhwevF22GMqNl8bYFrXfsFG5aOHZB3b9Y1g==",
  "timestamp": "1788242124123"
}

data示例

 {
  "deviceId": "ai123341",
  "params": {
    "topicId": 1
  }
}

参数

参数名	必选	类型	说明
topicId	是	int	话题id
key	是	string	apikey
deviceId	是	string	设备id
data	是	string	加密后的数据
timestamp	是	string	时间戳 13位毫秒

返回示例


{
  "code": 200,
  "msg": "success",
  "datas": {
    "topicId": 1,
    "topic": "我的文具",
    "gradeId": 1,
    "grade": "一年级",
    "role": [
      {
        "type": 0,
        "content": [
          {
            "sentence": "Hello, students! Do you have any stationery to show me?",
            "translate": "同学们，你们好!你有文具给我看看吗?",
            "tts": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/oral_training/teacher_mp3/1692168501523.mp3"
          },
          {
            "sentence": "That's nice! What else do you have in your pencil case?",
            "translate": "太好了!你的铅笔盒里还有什么?",
            "tts": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/oral_training/teacher_mp3/1692168498584.mp3"
          },
          {
            "sentence": "Good, an eraser is useful. What about colorful things?",
            "translate": "很好，橡皮擦很有用。彩色的东西呢?",
            "tts": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/oral_training/teacher_mp3/1692168500313.mp3"
          },
          {
            "sentence": "Great, crayons are fun! How about something to measure with?",
            "translate": "太好了，蜡笔很有趣!有什么可以测量的东西吗?",
            "tts": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/oral_training/teacher_mp3/1692164554428.mp3"
          },
          {
            "sentence": "Very useful! And what sticky thing do you have, if any?",
            "translate": "非常有用!你有什么黏糊糊的东西，如果有的话?",
            "tts": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/oral_training/teacher_mp3/1692168496234.mp3"
          }
        ]
      },
      {
        "type": 1,
        "content": [
          {
            "sentence": "Yes, I have a pencil.",
            "translate": "是的，我有一支铅笔。",
            "tts": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/oral_training/student_mp3/763639e90243514298c5ce975d693b2e_submit.mp3"
          },
          {
            "sentence": "I also have an eraser.",
            "translate": "我也有一块橡皮。",
            "tts": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/oral_training/student_mp3/763639e90243514298c5ce970d692b9e_submit.mp3"
          },
          {
            "sentence": "I have crayons, teacher.",
            "translate": "老师，我有蜡笔。",
            "tts": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/oral_training/student_mp3/763639e90243514298c5ce970d693b9e_submit.mp3"
          },
          {
            "sentence": "I brought a ruler.",
            "translate": "我带了一把尺子。",
            "tts": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/oral_training/student_mp3/763639e90243514298c5ce970d692b2e_submit.mp3"
          },
          {
            "sentence": "I have glue, teacher.",
            "translate": "老师，我有胶水。",
            "tts": "https://turing-appstore.oss-cn-beijing.aliyuncs.com/pad/oral_training/student_mp3/763639e90243514298c5ce970d694b9e_submit.mp3"
          }
        ]
      }
    ],
    "board": {
      "where": "两个朋友在学校的课间休息时间，其中一个朋友打开了他的文具盒，另一个朋友对他的文具感到好奇。",
      "who": "一个朋友（拥有文具盒）。",
      "task": "介绍和分享我拥有的文具，并与朋友讨论不同类型的文具。"
    }
  }
}

参数

参数名	类型	说明
grade	String	年级
gradeId	int	年级id
topic	String	话题
topicId	int	话题id
board	object	任务看板
where	String	任务看板里的场景
who	String	任务看板里的角色
task	String	任务看板里的任务
role	object	角色信息
type	int	AB角色
content	object	对话详情
sentence	String	对话详情中文文本
translate	String	对话详情英文文本
tts	String	对话详情tts音频