APIs 概述

欢迎使用 白泽国际中文智慧教学平台 APIs！本文档提供 CSCA（国际中文智慧教学平台）的 API 接口说明，帮助开发者快速集成和使用平台功能。

基本信息

  • Base URL: https://api.baizor.com/v1
  • 认证方式: Bearer Token
  • Content-Type: application/json

认证

所有 API 请求需要在 Header 中携带认证令牌：

Authorization: Bearer YOUR_ACCESS_TOKEN

响应格式

所有 API 响应统一返回 JSON 格式：

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

状态码

状态码说明
200请求成功
400请求参数错误
401未授权，Token 无效或过期
403禁止访问
404资源不存在
500服务器内部错误

用户权益

权益说明

白泽国际中文智慧教学平台 APIs 是为教育机构和开发者提供的专业服务，支持将 CSCA（国际中文智慧教学平台）的智能出题、自动测评等核心能力集成到您的教学系统或应用中。

请注意，本平台 API 权益仅供教育场景使用，包括学校教学、语言培训机构、在线教育平台等。禁止将 API 用于以下场景：

  • 违法违规内容生成或传播
  • 批量爬取、数据挖掘等非教育用途
  • 转售 API 额度或代理访问
  • 其他违反《用户服务协议》的行为

企业级定制需求请联系商务团队，我们提供专属服务方案，包括更高的调用额度、SLA 保障、私有化部署等。

计费方式

额度说明

CSCA API 调用采用额度制管理，不同用户等级享有不同的月度调用额度：

用户等级月度额度适用对象
免费版1,000 次个人开发者体验
教育版50,000 次认证教育机构
专业版200,000 次付费订阅用户
企业版定制额度签约合作机构

额度刷新逻辑

  • 额度按月刷新，每月 1 日 00:00 (UTC+8) 重置
  • 未使用额度不累计至下月
  • 额度用尽后可申请临时额度或升级套餐

超额计费

超出套餐额度的调用按量计费：

  • 出题 API：¥0.05/次
  • 测评 API：¥0.08/次

使用范围

CSCA API 权益可在以下场景使用：

  • 教学系统集成：将智能出题、测评功能嵌入学校 LMS 系统
  • 移动应用开发：开发中文学习类 App，调用平台核心能力
  • 在线课程平台：为课程内容提供配套练习和评测服务
  • 教学研究：学术研究、教学效果分析等非营利用途

支持的平台和工具：

  • 直接 HTTP API 调用
  • Python SDK（tongxin-csca）
  • JavaScript/Node.js SDK（@tongxin/csca-sdk）
  • Java SDK（Maven 依赖）

服务等级协议（SLA）

等级可用性承诺适用套餐
标准99.5%免费版、教育版
高级99.9%专业版
企业99.95%企业版

技术支持

  • 文档支持：完整的 API 文档和示例代码
  • 社区支持：开发者社区论坛交流
  • 工单支持：专业版及以上用户享有优先技术支持
  • 专属经理：企业版用户配备专属客户成功经理

如需变更套餐或了解更多权益详情，请参考《用户服务协议》或联系 support@tongxinhanyu.com。

CSCA APIs

CSCA（Chinese Smart Classroom API）提供中文教学相关的核心功能接口，包括智能出题和自动化测评。

CSCA 出题 API

智能生成中文学习题目，支持多种题型和难度级别。

请求

POST /csca/questions/generate

请求参数

参数类型必填说明
levelstring是难度级别：beginner, intermediate, advanced
typestring是题目类型：multiple_choice, fill_blank, matching, ordering
topicstring是主题分类，如：grammar, vocabulary, reading, listening
countinteger否生成题目数量，默认 10，最大 50
tagsarray否标签数组，用于筛选题目内容

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "questions": [
      {
        "id": "q_001",
        "type": "multiple_choice",
        "level": "intermediate",
        "question": "请选择正确的助词填空：我____去商店。",
        "options": [
          { "id": "A", "text": "把" },
          { "id": "B", "text": "被" },
          { "id": "C", "text": "要" },
          { "id": "D", "text": "让" }
        ],
        "correct_answer": "C",
        "explanation": "'要'表示意愿或计划，符合句子语境。",
        "tags": ["HSK3", "particles", "modal_verbs"]
      }
    ],
    "total": 5
  }
}

请求示例

{
  "level": "intermediate",
  "type": "multiple_choice",
  "topic": "grammar",
  "count": 5,
  "tags": ["HSK3", "particles"]
}

代码示例

curl -X POST "https://api.baizor.com/v1/csca/questions/generate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "level": "intermediate",
    "type": "multiple_choice",
    "topic": "grammar",
    "count": 5,
    "tags": ["HSK3", "particles"]
  }'

import requests

url = "https://api.baizor.com/v1/csca/questions/generate"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "level": "intermediate",
    "type": "multiple_choice",
    "topic": "grammar",
    "count": 5,
    "tags": ["HSK3", "particles"]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const url = 'https://api.baizor.com/v1/csca/questions/generate';
const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    level: 'intermediate',
    type: 'multiple_choice',
    topic: 'grammar',
    count: 5,
    tags: ['HSK3', 'particles']
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const data = JSON.stringify({
  level: 'intermediate',
  type: 'multiple_choice',
  topic: 'grammar',
  count: 5,
  tags: ['HSK3', 'particles']
});

const options = {
  hostname: 'api.baizor.com',
  path: '/v1/csca/questions/generate',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'Content-Length': data.length
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.write(data);
req.end();

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.baizor.com/v1/csca/questions/generate"
	data := map[string]interface{}{
		"level": "intermediate",
		"type":  "multiple_choice",
		"topic": "grammar",
		"count": 5,
		"tags":  []string{"HSK3", "particles"},
	}

	jsonData, _ := json.Marshal(data)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}
### 题目类型说明

类型说明
multiple_choice选择题
fill_blank填空题
matching配对题
ordering排序题

CSCA 测评 API

对学生作答进行智能评测，提供详细的学习分析和反馈。

请求

POST /csca/evaluation/submit

请求参数

参数类型必填说明
student_idstring是学生唯一标识
answersarray是答案数组
session_idstring否测评会话 ID

Answers 结构

字段类型说明
question_idstring题目 ID
answerstring/array学生答案
time_spentinteger答题用时（秒）

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "evaluation_id": "eval_abc123",
    "student_id": "stu_12345",
    "summary": {
      "total_questions": 10,
      "correct_count": 8,
      "score": 80,
      "time_spent": 850,
      "completion_rate": 1.0
    },
    "details": [
      {
        "question_id": "q_001",
        "is_correct": true,
        "score": 10,
        "feedback": "回答正确！",
        "time_spent": 45
      },
      {
        "question_id": "q_002",
        "is_correct": false,
        "score": 0,
        "feedback": "需要注意'的、地、得'的用法区别。",
        "suggestion": "建议复习：形容词+的+名词，副词+地+动词",
        "time_spent": 120
      }
    ],
    "analysis": {
      "strengths": ["词汇掌握良好", "语法基础扎实"],
      "weaknesses": ["助词使用需加强"],
      "recommendations": [
        {
          "type": "practice",
          "content": "建议练习 HSK3 级助词专项题目",
          "resources": ["res_001", "res_002"]
        }
      ]
    }
  }
}

请求示例

{
  "student_id": "stu_12345",
  "session_id": "sess_67890",
  "answers": [
    {
      "question_id": "q_001",
      "answer": "C",
      "time_spent": 45
    },
    {
      "question_id": "q_002",
      "answer": "北京是中国的首都。",
      "time_spent": 120
    }
  ]
}

代码示例

curl -X POST "https://api.baizor.com/v1/csca/evaluation/submit" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "stu_12345",
    "session_id": "sess_67890",
    "answers": [
      {
        "question_id": "q_001",
        "answer": "C",
        "time_spent": 45
      },
      {
        "question_id": "q_002",
        "answer": "北京是中国的首都。",
        "time_spent": 120
      }
    ]
  }'

import requests

url = "https://api.baizor.com/v1/csca/evaluation/submit"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "student_id": "stu_12345",
    "session_id": "sess_67890",
    "answers": [
        {
            "question_id": "q_001",
            "answer": "C",
            "time_spent": 45
        },
        {
            "question_id": "q_002",
            "answer": "北京是中国的首都。",
            "time_spent": 120
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const url = 'https://api.baizor.com/v1/csca/evaluation/submit';
const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    student_id: 'stu_12345',
    session_id: 'sess_67890',
    answers: [
      { question_id: 'q_001', answer: 'C', time_spent: 45 },
      { question_id: 'q_002', answer: '北京是中国的首都。', time_spent: 120 }
    ]
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const data = JSON.stringify({
  student_id: 'stu_12345',
  session_id: 'sess_67890',
  answers: [
    { question_id: 'q_001', answer: 'C', time_spent: 45 },
    { question_id: 'q_002', answer: '北京是中国的首都。', time_spent: 120 }
  ]
});

const options = {
  hostname: 'api.baizor.com',
  path: '/v1/csca/evaluation/submit',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'Content-Length': data.length
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.write(data);
req.end();

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.baizor.com/v1/csca/evaluation/submit"
	data := map[string]interface{}{
		"student_id": "stu_12345",
		"session_id": "sess_67890",
		"answers": []map[string]interface{}{
			{"question_id": "q_001", "answer": "C", "time_spent": 45},
			{"question_id": "q_002", "answer": "北京是中国的首都。", "time_spent": 120},
		},
	}

	jsonData, _ := json.Marshal(data)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}
### 获取测评结果

GET /csca/evaluation/{evaluation_id}

代码示例

curl -X GET "https://api.baizor.com/v1/csca/evaluation/eval_abc123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

evaluation_id = "eval_abc123"
url = f"https://api.baizor.com/v1/csca/evaluation/{evaluation_id}"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

const evaluationId = 'eval_abc123';
const url = `https://api.baizor.com/v1/csca/evaluation/${evaluationId}`;

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const evaluationId = 'eval_abc123';
const options = {
  hostname: 'api.baizor.com',
  path: `/v1/csca/evaluation/${evaluationId}`,
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.end();

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	evaluationId := "eval_abc123"
	url := fmt.Sprintf("https://api.baizor.com/v1/csca/evaluation/%s", evaluationId)
	
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}

获取学习报告

GET /csca/evaluation/report/{student_id}

代码示例

curl -X GET "https://api.baizor.com/v1/csca/evaluation/report/stu_12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

student_id = "stu_12345"
url = f"https://api.baizor.com/v1/csca/evaluation/report/{student_id}"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

const studentId = 'stu_12345';
const url = `https://api.baizor.com/v1/csca/evaluation/report/${studentId}`;

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const studentId = 'stu_12345';
const options = {
  hostname: 'api.baizor.com',
  path: `/v1/csca/evaluation/report/${studentId}`,
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.end();

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	studentId := "stu_12345"
	url := fmt.Sprintf("https://api.baizor.com/v1/csca/evaluation/report/%s", studentId)
	
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}

报告响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "student_id": "stu_12345",
    "period": "2024-01-01 to 2024-01-31",
    "overall_progress": {
      "score_trend": [65, 70, 75, 80, 82],
      "average_score": 74.4,
      "total_attempts": 25
    },
    "skill_analysis": {
      "vocabulary": { "score": 85, "level": "good" },
      "grammar": { "score": 78, "level": "average" },
      "reading": { "score": 82, "level": "good" },
      "listening": { "score": 70, "level": "average" }
    }
  }
}

智能评测 APIs

智能评测 APIs 提供中文口语、作文、篇章难度的自动化评测能力，基于国际中文教育研究成果构建。

口语评测 API

面向洋腔洋调人群的语音评测接口，基于多层次洋腔洋调语音评测指标体系，输出11个评测指标得分和总分。

请求

POST http://152.70.39.240:8005/uploadfile

请求参数

参数类型必填说明
filefile是语音文件（支持 wav、mp3 格式，时长不超过2分钟）
textstring是朗读标准文本（长度不超过2000字）

响应示例

{
    "filename": "1UFBK7V1PAN",
    "speed_of_speech_score": 63.16,
    "silent_pause_frequency_score": 0,
    "text_integrity_score": 96,
    "rate_of_pronunciation_score": 44.53,
    "pronunciation_time_ratio_score": 28.02,
    "pause_fluency_score": 100,
    "corrected_fluency_score": 95,
    "average_length_of_silent_pause_score": 0,
    "average_flow_length_score": 15.38,
    "sentence_intonation_score": 84.85,
    "accurary_score": 96,
    "total_score": 57.36
}

响应参数

参数类型说明
speed_of_speech_scorefloat语速得分
silent_pause_frequency_scorefloat无声停顿频率得分
text_integrity_scorefloat文本完整度得分
rate_of_pronunciation_scorefloat发音速度得分
pronunciation_time_ratio_scorefloat发音时间比得分
pause_fluency_scorefloat有声停顿频率得分
corrected_fluency_scorefloat非流利频率得分
average_length_of_silent_pause_scorefloat无声停顿平均长度得分
average_flow_length_scorefloat平均语流长度得分
sentence_intonation_scorefloat句调得分
accurary_scorefloat准确率得分
total_scorefloat总得分

代码示例

curl -X POST "http://152.70.39.240:8005/uploadfile" \
  -F "file=@/path/to/audio.wav" \
  -F "text=你好！你好！你叫什么名字？我叫阿尔达。很高兴认识你。"

import requests

url = "http://152.70.39.240:8005/uploadfile"
files = {
    'file': open('/path/to/audio.wav', 'rb')
}
data = {
    'text': '你好！你好！你叫什么名字？我叫阿尔达。很高兴认识你。'
}

response = requests.post(url, files=files, data=data)
print(response.json())

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('text', '你好！你好！你叫什么名字？我叫阿尔达。很高兴认识你。');

fetch('http://152.70.39.240:8005/uploadfile', {
  method: 'POST',
  body: formData
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const fs = require('fs');
const FormData = require('form-data');
const http = require('http');

const form = new FormData();
form.append('file', fs.createReadStream('/path/to/audio.wav'));
form.append('text', '你好！你好！你叫什么名字？我叫阿尔达。很高兴认识你。');

const options = {
  hostname: '152.70.39.240',
  port: 8005,
  path: '/uploadfile',
  method: 'POST',
  headers: form.getHeaders()
};

const req = http.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
form.pipe(req);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	url := "http://152.70.39.240:8005/uploadfile"
	
	var b bytes.Buffer
	w := multipart.NewWriter(&b)
	
	// Add file
	file, _ := os.Open("/path/to/audio.wav")
	defer file.Close()
	fw, _ := w.CreateFormFile("file", "audio.wav")
	io.Copy(fw, file)
	
	// Add text field
	fw, _ = w.CreateFormField("text")
	fw.Write([]byte("你好！你好！你叫什么名字？我叫阿尔达。很高兴认识你。"))
	w.Close()

	req, _ := http.NewRequest("POST", url, &b)
	req.Header.Set("Content-Type", w.FormDataContentType())

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}
### 指标说明

指标类别包含指标
流利度语速、发音速度、发音时间比、平均语流长度、有声/无声停顿频率
完整度文本完整度（漏读、多读、错读检测）
准确度声韵调准确度评分
句调句调群音高、时长评分

作文评测 API

基于AIGC大语言模型的留学生汉语作文自动批阅接口，采用RASNC提示词框架实现精准批改。

请求

POST /v1/essay/evaluate

请求参数

参数类型必填说明
student_idstring是学生唯一标识
essay_titlestring否作文题目
essay_contentstring是作文内容
hsk_levelstring否HSK等级（1-6），用于参考评分标准
frameworkstring否提示词框架：RASNC（默认）、RAC、APE

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "evaluation_id": "eval_essay_001",
    "overall_score": 78.5,
    "word_level": {
      "error_count": 3,
      "errors": [
        {
          "type": "别字",
          "original": "我家乡有美丽河流",
          "correction": "我的家乡有一条美丽的河流",
          "position": "1-5",
          "explanation": "缺少量词'一条'，'的'字使用不当"
        }
      ]
    },
    "sentence_level": {
      "grammar_errors": 2,
      "vocabulary_issues": 1
    },
    "discourse_level": {
      "structure_score": 80,
      "coherence_score": 75,
      "content_score": 82,
      "suggestions": ["建议增加段落间的过渡句", "结尾可以更加具体"]
    },
    "marked_version": "我的[L]家乡有[B]一条美丽[W]的河流。...",
    "corrected_version": "我的家乡有一条美丽的河流。那里的人们很友好..."
  }
}

响应参数

参数类型说明
evaluation_idstring评测任务ID
overall_scorefloat总分（0-100）
word_levelobject字词层面批改结果
sentence_levelobject句子层面批改结果
discourse_levelobject篇章层面评价
corrected_versionstring修正后的作文
marked_versionstring带批注标记的作文

批注标识符

标记含义示例
[B]别字标记，前接正确字的[B]地
[L]漏字标记[L]很
[D]多字标记的[D]
[P]标点错误[P]，
[W]词语错误[W]美丽→漂亮
[S]句子结构错误[S]

请求示例

{
  "student_id": "stu_12345",
  "essay_title": "我的家乡",
  "essay_content": "我家乡有美丽河流。那里的人很友好...",
  "hsk_level": "3",
  "framework": "RASNC"
}

代码示例

curl -X POST "https://api.baizor.com/v1/essay/evaluate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "stu_12345",
    "essay_title": "我的家乡",
    "essay_content": "我家乡有美丽河流。那里的人很友好...",
    "hsk_level": "3",
    "framework": "RASNC"
  }'

import requests

url = "https://api.baizor.com/v1/essay/evaluate"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "student_id": "stu_12345",
    "essay_title": "我的家乡",
    "essay_content": "我家乡有美丽河流。那里的人很友好...",
    "hsk_level": "3",
    "framework": "RASNC"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const url = 'https://api.baizor.com/v1/essay/evaluate';
const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    student_id: 'stu_12345',
    essay_title: '我的家乡',
    essay_content: '我家乡有美丽河流。那里的人很友好...',
    hsk_level: '3',
    framework: 'RASNC'
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const data = JSON.stringify({
  student_id: 'stu_12345',
  essay_title: '我的家乡',
  essay_content: '我家乡有美丽河流。那里的人很友好...',
  hsk_level: '3',
  framework: 'RASNC'
});

const options = {
  hostname: 'api.baizor.com',
  path: '/v1/essay/evaluate',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'Content-Length': data.length
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.write(data);
req.end();

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.baizor.com/v1/essay/evaluate"
	data := map[string]interface{}{
		"student_id":     "stu_12345",
		"essay_title":    "我的家乡",
		"essay_content":  "我家乡有美丽河流。那里的人很友好...",
		"hsk_level":      "3",
		"framework":      "RASNC",
	}

	jsonData, _ := json.Marshal(data)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}
### RASNC 提示词框架

要素说明
Role专业中文作文批改教师
Action逐句分析、详细批改
Step通读→标注→分析→评价
NormHSK动态作文语料库标注标准
Clarification错误原因说明与正确用法指导

篇章难度评测 API

基于《国际中文教育中文水平等级标准》的语法点检测框架（GP-NRR），自动识别文本中的语法点并评估难度等级。

请求

POST http://81.69.21.224:8665/grammar_text

请求参数

参数类型必填说明
txtstring是输入文本

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "grammar_list": [
      "【三02】", "【一08】", "【七—九062】", "【四04】", 
      "【五33】", "【二38】", "【二37】"
    ],
    "grammar_dict": {
      "【一01】": [[46, 48, "东南", "词语匹配"]],
      "【一07】": [[8, 9, "二", "词语匹配"]],
      "【二38】": [[19, 114, "简称...", "语义词性匹配"]],
      "【二60】": [[25, 26, "是", "固定搭配"]]
    },
    "difficulty_level": "4",
    "grammar_count": {
      "level_1": 12,
      "level_2": 8,
      "level_3": 5,
      "level_4": 3,
      "level_5": 2,
      "level_6_9": 1
    }
  }
}

响应参数

参数类型说明
grammar_listarray文本涉及的语法点列表
grammar_dictobject语法点在文本中的位置信息
difficulty_levelstring文本难度等级（1-7级）
grammar_countobject各级语法点数量统计

请求示例

{
  "txt": "在十七大中指出，二十三个省中的福建省，简称'闽'，是中华人民共和国省级行政区..."
}

代码示例

curl -X POST "http://81.69.21.224:8665/grammar_text" \
  -H "Content-Type: application/json" \
  -d '{
    "txt": "在十七大中指出，二十三个省中的福建省，简称'"'"'闽'"'"'，是中华人民共和国省级行政区..."
  }'

import requests

url = "http://81.69.21.224:8665/grammar_text"
headers = {
    "Content-Type": "application/json"
}
data = {
    "txt": "在十七大中指出，二十三个省中的福建省，简称'闽'，是中华人民共和国省级行政区..."
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const url = 'http://81.69.21.224:8665/grammar_text';
const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    txt: "在十七大中指出，二十三个省中的福建省，简称'闽'，是中华人民共和国省级行政区..."
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const http = require('http');

const data = JSON.stringify({
  txt: "在十七大中指出，二十三个省中的福建省，简称'闽'，是中华人民共和国省级行政区..."
});

const options = {
  hostname: '81.69.21.224',
  port: 8665,
  path: '/grammar_text',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length
  }
};

const req = http.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.write(data);
req.end();

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "http://81.69.21.224:8665/grammar_text"
	data := map[string]interface{}{
		"txt": "在十七大中指出，二十三个省中的福建省，简称'闽'，是中华人民共和国省级行政区...",
	}

	jsonData, _ := json.Marshal(data)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}
### 检测维度

匹配类型说明示例
词语匹配字词级别语法点量词、方位词
固定搭配匹配成语、惯用语“是…的"结构
模式匹配句型结构模式“把"字句、“被"字句
词性匹配基于词性的规则助词"过”+动词
短语匹配短语结构分析动宾短语、偏正短语
句法依存匹配句子成分关系主谓关系、动宾关系
语义匹配语义角色和逻辑时间语义、空间语义

语法点等级划分

覆盖《等级标准》572个语法点，分为七级：

  • 一级：基础词汇和简单句型
  • 二级：常用语法结构
  • 三级：复合句和复杂表达
  • 四级-六级：中高级语法点
  • 七-九级：高级及超纲语法点

智能导学 APIs

智能导学 APIs 提供学生能力画像、个性化推荐、知识地图等AI驱动的学习指导功能。

能力画像 API

构建多维度学生能力评估体系，包含85个叶子指标、36个三级指标、6个二级指标、3个一级指标。

首次能力画像

POST /v1/portrait/first

基于学生问卷和首次评测结果生成初始能力画像。

请求参数

参数类型必填说明
student_idstring是学生唯一标识
questionnaireobject是问卷结果
test_resultsobject是首次评测结果

请求示例

{
  "student_id": "stu_12345",
  "questionnaire": {
    "learning_goals": ["HSK4", "daily_conversation"],
    "native_language": "English",
    "learning_duration": "6_months"
  },
  "test_results": {
    "listen_ability": 65.0,
    "speak_ability": 60.0,
    "read_ability": 70.0,
    "write_ability": 62.0
  }
}

代码示例

curl -X POST "https://api.baizor.com/v1/portrait/first" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "stu_12345",
    "questionnaire": {
      "learning_goals": ["HSK4", "daily_conversation"],
      "native_language": "English",
      "learning_duration": "6_months"
    },
    "test_results": {
      "listen_ability": 65.0,
      "speak_ability": 60.0,
      "read_ability": 70.0,
      "write_ability": 62.0
    }
  }'

import requests

url = "https://api.baizor.com/v1/portrait/first"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "student_id": "stu_12345",
    "questionnaire": {
        "learning_goals": ["HSK4", "daily_conversation"],
        "native_language": "English",
        "learning_duration": "6_months"
    },
    "test_results": {
        "listen_ability": 65.0,
        "speak_ability": 60.0,
        "read_ability": 70.0,
        "write_ability": 62.0
    }
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const url = 'https://api.baizor.com/v1/portrait/first';
const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    student_id: 'stu_12345',
    questionnaire: {
      learning_goals: ['HSK4', 'daily_conversation'],
      native_language: 'English',
      learning_duration: '6_months'
    },
    test_results: {
      listen_ability: 65.0,
      speak_ability: 60.0,
      read_ability: 70.0,
      write_ability: 62.0
    }
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const data = JSON.stringify({
  student_id: 'stu_12345',
  questionnaire: {
    learning_goals: ['HSK4', 'daily_conversation'],
    native_language: 'English',
    learning_duration: '6_months'
  },
  test_results: {
    listen_ability: 65.0,
    speak_ability: 60.0,
    read_ability: 70.0,
    write_ability: 62.0
  }
});

const options = {
  hostname: 'api.baizor.com',
  path: '/v1/portrait/first',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'Content-Length': data.length
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.write(data);
req.end();

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.baizor.com/v1/portrait/first"
	data := map[string]interface{}{
		"student_id": "stu_12345",
		"questionnaire": map[string]interface{}{
			"learning_goals":     []string{"HSK4", "daily_conversation"},
			"native_language":    "English",
			"learning_duration": "6_months",
		},
		"test_results": map[string]float64{
			"listen_ability": 65.0,
			"speak_ability":  60.0,
			"read_ability":   70.0,
			"write_ability":  62.0,
		},
	}

	jsonData, _ := json.Marshal(data)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "student_id": "stu_12345",
    "first_portrait": {
      "listen_ability": 75.5,
      "speak_ability": 68.0,
      "read_ability": 82.3,
      "write_ability": 70.5,
      "comprehensive_ability": 74.1
    },
    "current_portrait": {
      "language_ability": {
        "listen": 78.5,
        "speak": 72.0,
        "read": 85.3,
        "write": 75.5
      },
      "classroom_performance": {
        "score": 82.0,
        "level": "铂金学习者"
      },
      "community_performance": {
        "score": 68.5,
        "level": "社交牛人"
      }
    },
    "level_labels": {
      "language": "中文达人",
      "star_level": 8,
      "star_exp": 560
    },
    "updated_at": "2024-01-15T08:30:00Z"
  }
}

响应参数

参数类型说明
listen_abilityfloat听力能力（0-100）
speak_abilityfloat口语能力（0-100）
read_abilityfloat阅读能力（0-100）
write_abilityfloat写作能力（0-100）
comprehensive_abilityfloat综合能力（0-100）
level_labelsobject能力等级标签

实时能力画像更新

POST /v1/portrait/update

根据学习行为数据每日更新能力画像。

更新维度

  • 时长类：完成时间、学习时长
  • 百分比类：完成进度、准确率
  • 等级类：分数、难度
  • 开关值类：是否提交作业
  • 次数类：签到次数、投票次数

获取能力画像

GET /v1/portrait/{student_id}

代码示例

curl -X GET "https://api.baizor.com/v1/portrait/stu_12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

student_id = "stu_12345"
url = f"https://api.baizor.com/v1/portrait/{student_id}"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

const studentId = 'stu_12345';
const url = `https://api.baizor.com/v1/portrait/${studentId}`;

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const studentId = 'stu_12345';
const options = {
  hostname: 'api.baizor.com',
  path: `/v1/portrait/${studentId}`,
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.end();

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	studentId := "stu_12345"
	url := fmt.Sprintf("https://api.baizor.com/v1/portrait/%s", studentId)
	
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}

代码示例

curl -X POST "https://api.baizor.com/v1/portrait/first" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "stu_12345",
    "questionnaire": {
      "learning_goals": ["HSK4", "daily_conversation"],
      "native_language": "English",
      "learning_duration": "6_months"
    },
    "test_results": {
      "listen_ability": 65.0,
      "speak_ability": 60.0,
      "read_ability": 70.0,
      "write_ability": 62.0
    }
  }'

import requests

url = "https://api.baizor.com/v1/portrait/first"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "student_id": "stu_12345",
    "questionnaire": {
        "learning_goals": ["HSK4", "daily_conversation"],
        "native_language": "English",
        "learning_duration": "6_months"
    },
    "test_results": {
        "listen_ability": 65.0,
        "speak_ability": 60.0,
        "read_ability": 70.0,
        "write_ability": 62.0
    }
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const url = 'https://api.baizor.com/v1/portrait/first';
const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    student_id: 'stu_12345',
    questionnaire: {
      learning_goals: ['HSK4', 'daily_conversation'],
      native_language: 'English',
      learning_duration: '6_months'
    },
    test_results: {
      listen_ability: 65.0,
      speak_ability: 60.0,
      read_ability: 70.0,
      write_ability: 62.0
    }
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const data = JSON.stringify({
  student_id: 'stu_12345',
  questionnaire: {
    learning_goals: ['HSK4', 'daily_conversation'],
    native_language: 'English',
    learning_duration: '6_months'
  },
  test_results: {
    listen_ability: 65.0,
    speak_ability: 60.0,
    read_ability: 70.0,
    write_ability: 62.0
  }
});

const options = {
  hostname: 'api.baizor.com',
  path: '/v1/portrait/first',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'Content-Length': data.length
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.write(data);
req.end();

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.baizor.com/v1/portrait/first"
	data := map[string]interface{}{
		"student_id": "stu_12345",
		"questionnaire": map[string]interface{}{
			"learning_goals":     []string{"HSK4", "daily_conversation"},
			"native_language":    "English",
			"learning_duration": "6_months",
		},
		"test_results": map[string]float64{
			"listen_ability": 65.0,
			"speak_ability":  60.0,
			"read_ability":   70.0,
			"write_ability":  62.0,
		},
	}

	jsonData, _ := json.Marshal(data)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}
### 能力等级标签

类别等级划分分数范围
语言能力中文大师 / 中文达人 / 中文能手 / 中文小白≥85 / 60-85 / 20-60 / <20
课堂表现钻石 / 铂金 / 黄金 / 白银学习者≥85 / 60-85 / 20-60 / <20
社区表现社交名人 / 社交牛人 / 社交新人≥85 / 20-85 / <20

星级体系

星级所需经验星级所需经验
1星509星960
2星11010星1200
3星17011星1460
4星23012星1720
5星29013星1980
6星41014星2260
7星53015星2540
8星560--

推荐出题 API

系统根据学生的学习能力和水平每日推荐个性化练习题和学习资源。

获取每日推荐

GET /v1/recommendation/daily/{student_id}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "date": "2024-01-15",
    "student_id": "stu_12345",
    "recommendations": [
      {
        "resource_id": "q_001",
        "resource_type": "question",
        "title": "听力理解练习",
        "difficulty": "HSK3",
        "skill_type": "listening",
        "start_time": "07:00",
        "end_time": "08:00",
        "time_slot": "morning",
        "count": 6
      },
      {
        "resource_id": "v_025",
        "resource_type": "video",
        "title": "日常对话视频",
        "difficulty": "HSK3",
        "skill_type": "listening",
        "duration": 30,
        "start_time": "07:30",
        "end_time": "08:00",
        "time_slot": "morning"
      }
    ],
    "schedule": {
      "morning": {
        "period": "07:00-08:00",
        "focus": "listening",
        "items": 2,
        "duration": 60
      },
      "noon": {
        "period": "12:00-14:30",
        "focus": "reading",
        "items": 3,
        "duration": 90
      }
    },
    "total_duration": 210
  }
}

请求参数

参数类型必填说明
datestring否推荐日期（YYYY-MM-DD），默认为当天
time_slotstring否时段标签：morning、noon、evening、night

响应参数

参数类型说明
recommendationsarray推荐内容列表
scheduleobject自适应日程安排
total_durationinteger预计学习时长（分钟）

推荐内容结构

字段类型说明
resource_idstring资源ID
resource_typestring类型：question、video、audio
titlestring资源标题
difficultystring难度等级
skill_typestring技能类型：听、说、读、写
start_timestring推荐开始时间
end_timestring推荐结束时间
time_slotstring时段标签

代码示例

curl -X GET "https://api.baizor.com/v1/recommendation/daily/stu_12345?date=2024-01-15&time_slot=morning" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

student_id = "stu_12345"
url = f"https://api.baizor.com/v1/recommendation/daily/{student_id}"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
params = {
    "date": "2024-01-15",
    "time_slot": "morning"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const studentId = 'stu_12345';
const url = new URL(`https://api.baizor.com/v1/recommendation/daily/${studentId}`);
url.searchParams.append('date', '2024-01-15');
url.searchParams.append('time_slot', 'morning');

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const studentId = 'stu_12345';
const options = {
  hostname: 'api.baizor.com',
  path: `/v1/recommendation/daily/${studentId}?date=2024-01-15&time_slot=morning`,
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.end();

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	studentId := "stu_12345"
	url := fmt.Sprintf("https://api.baizor.com/v1/recommendation/daily/%s?date=2024-01-15&time_slot=morning", studentId)
	
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}
### 推荐时段配置

时段时间范围重点技能推荐数量
早间07:00-08:00听力 > 口语 > 阅读 > 书写6题+30分钟视频
午间12:00-14:30阅读 > 书写 > 听力 > 口语12题+30分钟视频
晚间18:00-19:30口语 > 书写 > 听力 > 阅读9题+40分钟视频
夜间21:30-24:00书写 > 阅读 > 听力 > 口语15题+50分钟视频
周末07:00-12:00均衡分配25题+50分钟视频

更新日程安排

POST /v1/recommendation/schedule

学生可自由调整推荐内容的时间段标签。

请求示例

{
  "student_id": "stu_12345",
  "resource_id": "q_001",
  "new_time_slot": "evening",
  "new_start_time": "19:00",
  "new_end_time": "20:00"
}

代码示例

curl -X POST "https://api.baizor.com/v1/recommendation/schedule" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "student_id": "stu_12345",
    "resource_id": "q_001",
    "new_time_slot": "evening",
    "new_start_time": "19:00",
    "new_end_time": "20:00"
  }'

import requests

url = "https://api.baizor.com/v1/recommendation/schedule"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "student_id": "stu_12345",
    "resource_id": "q_001",
    "new_time_slot": "evening",
    "new_start_time": "19:00",
    "new_end_time": "20:00"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const url = 'https://api.baizor.com/v1/recommendation/schedule';
const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    student_id: 'stu_12345',
    resource_id: 'q_001',
    new_time_slot: 'evening',
    new_start_time: '19:00',
    new_end_time: '20:00'
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const data = JSON.stringify({
  student_id: 'stu_12345',
  resource_id: 'q_001',
  new_time_slot: 'evening',
  new_start_time: '19:00',
  new_end_time: '20:00'
});

const options = {
  hostname: 'api.baizor.com',
  path: '/v1/recommendation/schedule',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'Content-Length': data.length
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.write(data);
req.end();

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.baizor.com/v1/recommendation/schedule"
	data := map[string]interface{}{
		"student_id":      "stu_12345",
		"resource_id":     "q_001",
		"new_time_slot":   "evening",
		"new_start_time": "19:00",
		"new_end_time":    "20:00",
	}

	jsonData, _ := json.Marshal(data)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}

知识地图 API

记录学生在853个知识点的掌握程度，通过可视化地图直观展示学习成果。

获取知识地图

GET /v1/knowledge-map/{student_id}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "student_id": "stu_12345",
    "knowledge_points": [
      {
        "point_id": "【一01】",
        "name": "方位词",
        "status": "mastered",
        "color": "green",
        "total_attempts": 15,
        "correct_count": 14,
        "accuracy": 0.93,
        "parent_id": "level_1"
      },
      {
        "point_id": "【二38】",
        "name": "语义词性匹配",
        "status": "learning",
        "color": "blue",
        "total_attempts": 8,
        "correct_count": 4,
        "accuracy": 0.50,
        "parent_id": "level_2"
      }
    ],
    "mastery_stats": {
      "excellent": 120,
      "good": 280,
      "average": 350,
      "not_started": 103
    },
    "learning_path": {
      "hsk_path": ["【一01】", "【一02】", "【二38】", "【三02】"],
      "recommended_resources": ["res_001", "res_002", "res_003"]
    },
    "peers": [
      {
        "student_id": "stu_67890",
        "similarity": 0.85,
        "knowledge_overlap": 720
      }
    ],
    "updated_at": "2024-01-15T02:00:00Z"
  }
}

请求参数

参数类型必填说明
subjectstring否学科类型：hsk（默认）、ykk

响应参数

参数类型说明
knowledge_pointsarray853维知识点掌握情况
mastery_statsobject掌握程度统计
learning_patharray推荐学习路径
peersarray匹配的学习同伴

知识点掌握状态

状态颜色标记判定条件
超标黄色正确率 > 90%
已达标绿色正确率 60%-90%
未达标蓝色正确率 < 60%
未学习灰色无学习记录

代码示例

curl -X GET "https://api.baizor.com/v1/knowledge-map/stu_12345?subject=hsk" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

student_id = "stu_12345"
url = f"https://api.baizor.com/v1/knowledge-map/{student_id}"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
params = {
    "subject": "hsk"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const studentId = 'stu_12345';
const url = new URL(`https://api.baizor.com/v1/knowledge-map/${studentId}`);
url.searchParams.append('subject', 'hsk');

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const studentId = 'stu_12345';
const options = {
  hostname: 'api.baizor.com',
  path: `/v1/knowledge-map/${studentId}?subject=hsk`,
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.end();

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	studentId := "stu_12345"
	url := fmt.Sprintf("https://api.baizor.com/v1/knowledge-map/%s?subject=hsk", studentId)
	
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}
### 更新知识地图

POST /v1/knowledge-map/update

每日凌晨2点自动增量更新知识地图。

更新逻辑

  1. 抓取前一日新增做题记录
  2. 计算涉及知识点的掌握程度
  3. 增量更新853维知识地图向量
  4. 重新计算父节点状态

获取学习路径

GET /v1/knowledge-map/{student_id}/path

代码示例

curl -X GET "https://api.baizor.com/v1/knowledge-map/stu_12345/path" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

student_id = "stu_12345"
url = f"https://api.baizor.com/v1/knowledge-map/{student_id}/path"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

const studentId = 'stu_12345';
const url = `https://api.baizor.com/v1/knowledge-map/${studentId}/path`;

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const studentId = 'stu_12345';
const options = {
  hostname: 'api.baizor.com',
  path: `/v1/knowledge-map/${studentId}/path`,
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.end();

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	studentId := "stu_12345"
	url := fmt.Sprintf("https://api.baizor.com/v1/knowledge-map/%s/path", studentId)
	
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}

响应示例

{
  "code": 200,
  "data": {
    "current_level": "HSK3",
    "target_level": "HSK4",
    "path": [
      {
        "stage": 1,
        "points": ["【三02】", "【三51】", "【三74】"],
        "resources": ["video_001", "quiz_001"],
        "estimated_duration": 120
      }
    ],
    "shortest_path": 14665,
    "recommended_path": 12800
  }
}

查找学习同伴

GET /v1/knowledge-map/{student_id}/peers

基于知识地图相似度计算匹配学习同伴。

代码示例

curl -X GET "https://api.baizor.com/v1/knowledge-map/stu_12345/peers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

student_id = "stu_12345"
url = f"https://api.baizor.com/v1/knowledge-map/{student_id}/peers"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

const studentId = 'stu_12345';
const url = `https://api.baizor.com/v1/knowledge-map/${studentId}/peers`;

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

const https = require('https');

const studentId = 'stu_12345';
const options = {
  hostname: 'api.baizor.com',
  path: `/v1/knowledge-map/${studentId}/peers`,
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
};

const req = https.request(options, (res) => {
  let responseData = '';
  res.on('data', (chunk) => { responseData += chunk; });
  res.on('end', () => { console.log(JSON.parse(responseData)); });
});

req.on('error', (error) => { console.error(error); });
req.end();

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	studentId := "stu_12345"
	url := fmt.Sprintf("https://api.baizor.com/v1/knowledge-map/%s/peers", studentId)
	
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result)
}

错误处理

当 API 调用发生错误时，响应将包含详细的错误信息：

{
  "code": 400,
  "message": "参数验证失败",
  "errors": [
    {
      "field": "level",
      "message": "无效的难度级别，可选值为：beginner, intermediate, advanced"
    }
  ]
}

常见错误

错误码说明解决方案
400001参数缺失检查必填参数是否完整
400002参数格式错误检查参数类型和格式
401001Token 过期重新获取访问令牌
403001权限不足检查 API 密钥权限配置
429001请求过于频繁降低请求频率或升级套餐

SDK 与工具

我们提供多种语言的 SDK，方便您快速接入：

  • Python: pip install tongxin-csca
  • JavaScript/Node.js: npm install @tongxin/csca-sdk
  • Java: Maven 依赖 com.tongxin:csca-sdk:1.0.0

Python 示例

from tongxin_csca import CSCAClient

client = CSCAClient(api_key="your_api_key")

# 生成题目
questions = client.generate_questions(
    level="intermediate",
    type_="multiple_choice",
    topic="grammar",
    count=5
)

# 提交测评
result = client.submit_evaluation(
    student_id="stu_12345",
    answers=[...]
)