作文批改 API 文档

1. 接口概述

1.1 基本信息

接口地址: https://hexeltsiting-fc-kuapjgzhvy.cn-hangzhou.fcapp.run/process_essay
请求方式: POST
数据格式: JSON
响应类型: Server-Sent Events (SSE)
字符编码: UTF-8

1.2 功能说明

提供 IELTS 写作评分和分析服务，支持 Task1 和 Task2 两种类型的作文评估。

2. 认证方式

2.1 请求头

字段	必填	说明
X-API-Key	是	API访问密钥
X-Timestamp	是	当前UNIX时间戳（秒）
X-Signature	是	请求签名
Content-Type	是	固定值: application/json

2.2 签名算法

signature = HMAC-SHA256(timestamp + request_body, api_key)

request_body 必须与实际发送的请求体完全一致（包括空格和换行）
签名结果使用16进制小写字符串表示

3. 请求格式

3.1 请求体结构

json

{
    "raw_essay": {
        "essay_requirement": "作文要求",
        "essay_content": "作文内容",
        "image": "图片URL（可选）"
    },
    "language": "中文",
    "type": "ielts_task1",
    "level": "advanced"
}

3.2 字段说明

字段	类型	必填	说明
raw_essay.essay_requirement	string	是	作文题目要求
raw_essay.essay_content	string	是	作文内容
raw_essay.image	string	否	相关图片URL
language	string	是	响应语言，支持"中文"/"英文"
type	string	是	作文类型："ielts_task1"/"ielts_task2"
level	string	是	评估级别："simple"/"standard"/"advanced"

4. 响应格式

4.1 SSE 数据格式

服务器会以 SSE 格式实时返回多个处理结果，每个结果的格式如下：

json

{
    "step": "处理步骤",
    "data": {
        // 处理结果数据
    },
    "status": "success",
    "error": null
}

4.2 处理步骤说明

注意：以下处理时间为模拟测试环境下的参考值，实际处理时间会根据服务器负载、网络状况和输入内容的复杂度而变化。

Task 1 基础(simple)模式：

步骤	参考耗时(秒)	说明	返回数据
grammar_correction	~1	语法纠错	纠错结果
corrected_essay	~0	返回纠错后的文本	完整的纠错后文本
grammar_analysis	~1	语法分析	语法分析结果

Task 1 标准(standard)模式：

步骤	参考耗时(秒)	说明	返回数据
grammar_correction	~1	语法纠错	纠错结果
corrected_essay	~0	返回纠错后的文本	完整的纠错后文本
grammar_analysis	~1	语法分析	语法分析结果
enhancement_sentence	~30	句子润色和优化	润色结果
task_1_overall	~5	整体评分和评价	评分和评价
task_1_logic_0	~20	初步逻辑分析	初步逻辑分析结果

Task 1 高级(advanced)模式：

步骤	参考耗时(秒)	说明	返回数据
grammar_correction	~1	语法纠错	纠错结果
corrected_essay	~0	返回纠错后的文本	完整的纠错后文本
grammar_analysis	~1	语法分析	语法分析结果
enhancement_sentence	~30	句子润色和优化	润色结果
task_1_overall	~5	整体评分和评价	评分和评价
task_1_raw	~5	原始文本分析	原始分析结果
task_1_logic_0	~20	初步逻辑分析	初步逻辑分析结果
task_1_logic_1	~20	深度逻辑分析	深度逻辑分析结果

Task 2 基础(simple)模式：

步骤	参考耗时(秒)	说明	返回数据
grammar_correction	~1	语法纠错	纠错结果
corrected_essay	~0	返回纠错后的文本	完整的纠错后文本
grammar_analysis	~1	语法分析	语法分析结果

Task 2 标准(standard)模式：

步骤	参考耗时(秒)	说明	返回数据
grammar_correction	~1	语法纠错	纠错结果
corrected_essay	~0	返回纠错后的文本	完整的纠错后文本
grammar_analysis	~1	语法分析	语法分析结果
enhancement_sentence	~30	句子润色和优化	润色结果
task_2_overall	~5	整体评分和评价	评分和评价
task_2_raw	~5	原始文本分析	原始分析结果
task_2_cohesion	~20	文本连贯性分析	连贯性分析结果
task_2_logic_0	~20	初步逻辑分析	初步逻辑分析结果

Task 2 高级(advanced)模式：

步骤	参考耗时(秒)	说明	返回数据
grammar_correction	~1	语法纠错	纠错结果
corrected_essay	~0	返回纠错后的文本	完整的纠错后文本
grammar_analysis	~1	语法分析	语法分析结果
enhancement_sentence	~30	句子润色和优化	润色结果
task_2_overall	~5	整体评分和评价	评分和评价
task_2_raw	~5	原始文本分析	原始分析结果
task_2_cohesion	~20	文本连贯性分析	连贯性分析结果
task_2_logic_0	~20	初步逻辑分析	初步逻辑分析结果
task_2_logic_1	~30	中级逻辑分析	中级逻辑分析结果
task_2_logic_2	~40	深度逻辑分析	深度逻辑分析结果

处理时间说明：

参考耗时仅供参考，实际处理时间可能会有波动
建议客户端超时设置不少于 300 秒
所有结果会通过 SSE 实时返回，无需等待所有步骤完成
语法纠错(grammar_correction) 和语法分析(grammar_analysis) 首先完成
大部分步骤会并行处理以提高效率, 因此总处理时间不是所有步骤时间的简单相加
Task2高级模式的特殊说明：
- task_2_logic_0、task_2_logic_1、task_2_logic_2 这三个逻辑分析步骤会按顺序执行
- 这三个步骤作为整体与其他功能（如句子润色、整体评价等）并行处理
- 因此总处理时间不是所有步骤时间的简单相加
simple(基础)模式说明：
- 仅执行语法纠错和语法分析
- 不包含其他高级分析功能

5. 错误处理

5.1 HTTP状态码

状态码	说明
200	请求成功
401	认证失败
412	函数执行错误
500	服务器内部错误

5.2 错误响应格式

json

{
    "step": "task_error",
    "data": {},
    "status": "error",
    "error": "错误描述"
}

6. 调用示例

6.1 cURL

bash

curl -X POST 'https://hexeltsiting-fc-kuapjgzhvy.cn-hangzhou.fcapp.run/process_essay' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: your-api-key' \
-H "X-Timestamp: $TIMESTAMP" \
-H 'X-Signature: calculated-signature' \
-d '{
    "raw_essay": {
        "essay_requirement": "The graph shows...",
        "essay_content": "The two maps compare...",
        "image": "http://example.com/image.jpg"
    },
    "language": "中文",
    "type": "ielts_task1",
    "level": "advanced"
}'

6.2 注意事项

请求必须使用 HTTP/1.1 或更高版本
客户端需要支持 SSE (Server-Sent Events) 接收流式响应
建议设置合理的超时时间（不少于300秒）
签名计算时注意保持请求体的一致性
所有文本内容必须使用 UTF-8 编码
不同级别(simple/standard/advanced)会返回不同数量的分析结果

7. 请求流程

7.1 基本请求流程

7.2 数据流说明

客户端发起请求
- 准备请求数据
- 计算请求签名
- 发送POST请求
服务器验证请求
- 验证API密钥
- 验证时间戳
- 验证请求签名
处理器并行处理
- 同时启动多个分析任务
- 任务完成即返回结果
结果实时推送
- 使用SSE协议推送结果
- 每个任务完成后立即推送
- 所有任务完成后关闭连接

8. 参考代码

python

import requests
import json
import time
import hmac
import hashlib
from typing import Dict, Any

# 测试用例数据
input_data = {
    "raw_essay": {
        "essay_requirement":"The graph shows the development of a particular college campus from 1975 to 2002 and the proposed development of 2020.\n\nSummarize the details.\n\nSelect and report the main features and make comparisons where relevant.",
        "essay_content": "The two maps compare changes in the layout of a specific university campus in 1975, 2002 and 2020.\n\nIn 1975, four main areas could be noticed in each corner of the university with several trees between them.\n\nIn the north-western corner a sports center was situated, surrounded by a road which intersected another road leading to a lecture room in the south-eastern part. A library lay in the south-western end and to its opposite side, there was a drama room and a music room boarding a big car park.\n\nIn 2002, one striking change was that the sports center had been removed and an indoor one is planned for 2020. Also the road running across the campus was demolished in order to make way for a science building in the center. But another new road will be build to connect the indoor sports center with the former library which had been divided into two so that half part served as an IT room. While the lecture room had become twice as large as it was in 1975, the original drama room was turned into a geology room, the place before which was gained by the car park, so its capacity was enlarged.\n\nIn summary, great changes had occurred as this university had more constructions over these years.",
        "image": "http://www-static.zhan.com/uploadfile/2018/10/30/5122822_20181030132422100gg.jpg"
    },
    "language": "中文",
    "type": "ielts_task1",
    "level": "advanced"
}

def generate_signature(api_key: str, timestamp: str, body: str) -> str:
    """生成请求签名"""
    return hmac.new(
        api_key.encode('utf-8'),
        f"{timestamp}{body}".encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

def call_process_essay(input_data: Dict[str, Any]) -> None:
    """
    调用作文处理API并处理响应
    
    Args:
        input_data: 包含作文内容和配置的字典
    """
    # API配置
    url = 'https://hexeltsiting-fc-kuapjgzhvy.cn-hangzhou.fcapp.run/process_essay'
    api_key = 'YOUR_API_KEY'
    timestamp = str(int(time.time()))
    body = json.dumps(input_data)
    signature = generate_signature(api_key, timestamp, body)
    
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': api_key,
        'X-Timestamp': timestamp,
        'X-Signature': signature
    }
    
    try:
        print("发送请求到服务器...")
        print(f"请求数据大小: {len(json.dumps(input_data))} 字符")
        
        # 发送请求
        response = requests.post(
            url=url,
            headers=headers,
            json=input_data,  # 使用json参数自动处理序列化
            stream=True
        )
        
        print(f"\n响应状态: {response.status_code}")
        print(f"响应头: {dict(response.headers)}\n")
        
        if response.status_code == 200:
            print("处理响应流:")
            print("-" * 50)
            
            for line in response.iter_lines(decode_unicode=True):
                if line.startswith('data: '):
                    try:
                        # 解析SSE数据
                        json_data = line[6:]  # 移除 'data: ' 前缀
                        response_json = json.loads(json_data)
                        pretty_response = json.dumps(
                            response_json,
                            ensure_ascii=False,
                            indent=2
                        )
                        print(f"\n接收到的数据:\n{pretty_response}")
                        print("-" * 50)
                    except json.JSONDecodeError as e:
                        print(f"JSON解析错误: {e}")
                        print(f"原始数据: {json_data}")
        else:
            print(f"请求失败，状态码: {response.status_code}")
            print(f"错误信息: {response.text}")
            
    except requests.exceptions.ConnectionError:
        print("连接错误: 请确保服务器正在运行")
    except Exception as e:
        print(f"意外错误: {str(e)}")

def main():
    """主函数"""
    print("开始API测试...")
    call_process_essay(input_data)

if __name__ == "__main__":
    main()

作文批改 API 文档 ​

1. 接口概述 ​

1.1 基本信息 ​

1.2 功能说明 ​

2. 认证方式 ​

2.1 请求头 ​

2.2 签名算法 ​

3. 请求格式 ​

3.1 请求体结构 ​

3.2 字段说明 ​

4. 响应格式 ​

4.1 SSE 数据格式 ​

4.2 处理步骤说明 ​

5. 错误处理 ​

5.1 HTTP状态码 ​

5.2 错误响应格式 ​

6. 调用示例 ​

6.1 cURL ​

6.2 注意事项 ​

7. 请求流程 ​

7.1 基本请求流程 ​

7.2 数据流说明 ​

8. 参考代码 ​

作文批改 API 文档

1. 接口概述

1.1 基本信息

1.2 功能说明

2. 认证方式

2.1 请求头

2.2 签名算法

3. 请求格式

3.1 请求体结构

3.2 字段说明

4. 响应格式

4.1 SSE 数据格式

4.2 处理步骤说明

5. 错误处理

5.1 HTTP状态码

5.2 错误响应格式

6. 调用示例

6.1 cURL

6.2 注意事项

7. 请求流程

7.1 基本请求流程

7.2 数据流说明

8. 参考代码