APIs 概述

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

基本信息

  • Base URL: https://api.tongxinhanyu.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否标签数组，用于筛选题目内容

请求示例

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

响应示例

{
  "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
  }
}

题目类型说明

类型说明
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答题用时（秒）

请求示例

{
  "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
    }
  ]
}

响应示例

{
  "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"]
        }
      ]
    }
  }
}

获取测评结果

GET /csca/evaluation/{evaluation_id}

获取学习报告

GET /csca/evaluation/report/{student_id}

报告响应示例

{
  "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" }
    }
  }
}

错误处理

当 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=[...]
)