作文批改报告PDF下载 API 文档

1. 接口概述

1.1 基本信息

• 接口地址
• 请求方式: POST

1.2 功能说明

返回提供 IELTS 的写作报告的PDF的下载链接.

2. 使用说明

根据不同的作文类型(Task 1/Task 2)和模式(simple/standard/advanced)，需要提供不同的数据字段。

2.1 字段要求

• Task 1 作文：不需要提供 logic_chain 字段
• Task 2 作文：需要提供所有对应模式的字段

2.2 模式说明

• simple模式：填 base_info, score, correction
• standard模式：填 base_info, score, correction, enhancement, analyse, material
• advanced模式：填所有字段

3. 请求格式

3.1 请求体结构

simple

{
  "base_info": object,    // 基础信息
  "score": object,        // 评分报告数据
  "correction": object,   // 语法纠错数据
}

standard

{
  "base_info": object,    // 基础信息
  "score": object,        // 评分报告数据
  "correction": object,   // 语法纠错数据
  "enhancement": object,  // 表达润色数据
  "analyse": object,      // 审题分析数据
  "material": object,     // 素材积累数据
}

advanced

{
  "base_info": object,    // 基础信息
  "score": object,        // 评分报告数据
  "correction": object,   // 语法纠错数据
  "enhancement": object,  // 表达润色数据
  "analyse": object,      // 审题分析数据
  "material": object,     // 素材积累数据
  "logic_chain": object, // 逻辑链数据, 注意 task 1 不用填因为没有
  "logic": object        // 逻辑分析数据
}

其中, 因为 task 1 没有 logic_chain 数据, 因此如果是 task 1 作文就不用填这个字段

结构信息

全部来自作文批改API调用和返回的字段.

base_info: 是作文批改API调用的JSON字段, 详细请见作文批改API. 具体如下:

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

其中 task 2 作文没有 image 数据因此没有这个字段.

其余的:

字段名	说明	数据文档
score	评分报告	评分报告结果
correction	语法纠错	纠错结果
grammar_analysis	语法分析	语法分析结果
enhancement	表达润色	表达优化建议
analyse	审题分析	内容分析结果
material	素材积累	相关素材推荐
logic_chain	逻辑链	逻辑链分析结果
logic	逻辑分析	逻辑分析结果

注意, 这些数据需要是批改API返回的完整的数据, 或者至少包含"step"和"data"字段 例如

{
    "step": "score",
    "data": {
        "main_scores": {...},
        "overall_comment": "...",
        "detailed_scores": {...}
    }
}

3.2 请求头

Content-Type: application/json

4. 响应格式

4.1 成功响应

• Content-Type: text/plain
• 响应内容: PDF文件的下载链接(字符串格式)

4.2 PDF下载

• 请求方式: GET
• 响应格式: application/pdf
• 响应内容: PDF文件二进制数据

5. 错误处理

5.1 错误码说明

当发生错误时，服务器会返回相应的HTTP状态码：

• 状态码: 4xx/5xx
  • 400: 请求参数错误
  • 401: 未授权访问
  • 500: 服务器内部错误
• Content-Type: application/json
• 响应体包含具体的错误信息

6. 调用示例

const axios = require('axios');
const fs = require('fs');
const path = require('path');

const URL = '接口地址';

let baseInfoData;
try {
  const baseInfoFilePath = path.resolve('./json/base_info.json');
  console.log(`尝试从 ${baseInfoFilePath} 读取 base_info 数据`);
  baseInfoData = JSON.parse(fs.readFileSync(baseInfoFilePath, 'utf8'));
  console.log('已成功加载 base_info 数据');
} catch (error) {
  console.error('无法读取 base_info 数据文件:', error.message);
  process.exit(1);
}

// 读取 score 数据
let scoreData;
try {
  const scoreFilePath = path.resolve('./json/score_1742897851656.json');
  console.log(`尝试从 ${scoreFilePath} 读取 score 数据`);
  scoreData = JSON.parse(fs.readFileSync(scoreFilePath, 'utf8'));
  console.log('已成功加载 score 数据');
} catch (error) {
  console.error('无法读取 score 数据文件:', error.message);
  process.exit(1);
}

// 读取 enhancement 数据
let enhancementData;
try {
  const enhancementFilePath = path.resolve('./json/enhancement_1742417321977.json');
  console.log(`尝试从 ${enhancementFilePath} 读取 enhancement 数据`);
  enhancementData = JSON.parse(fs.readFileSync(enhancementFilePath, 'utf8'));
  console.log('已成功加载 enhancement 数据');
} catch (error) {
  console.error('无法读取 enhancement 数据文件:', error.message);
  process.exit(1);
}

// 读取 correction 数据
let correctionData;
try {
  const correctionFilePath = path.resolve('./json/correction_1742552117403.json');
  console.log(`尝试从 ${correctionFilePath} 读取 correction 数据`);
  correctionData = JSON.parse(fs.readFileSync(correctionFilePath, 'utf8'));
  console.log('已成功加载 correction 数据');
} catch (error) {
  console.error('无法读取 correction 数据文件:', error.message);
  process.exit(1);
}

// 读取 analyse 数据
let analyseData;
try {
  const analyseFilePath = path.resolve('./json/analyse_1742552218826.json');
  console.log(`尝试从 ${analyseFilePath} 读取 analyse 数据`);
  analyseData = JSON.parse(fs.readFileSync(analyseFilePath, 'utf8'));
  console.log('已成功加载 analyse 数据');
} catch (error) {
  console.error('无法读取 analyse 数据文件:', error.message);
  process.exit(1);
}

// 读取 material 数据
let materialData;
try {
  const materialFilePath = path.resolve('./json/material_1742897757580.json');
  console.log(`尝试从 ${materialFilePath} 读取 material 数据`);
  materialData = JSON.parse(fs.readFileSync(materialFilePath, 'utf8'));
  console.log('已成功加载 material 数据');
} catch (error) {
  console.error('无法读取 material 数据文件:', error.message);
  process.exit(1);
}

//读取 logic-chain 数据
let logicChainData;
try {
  const logicChainFilePath = path.resolve('./json/logic_chain_1742897855277.json');
  console.log(`尝试从 ${logicChainFilePath} 读取 logic-chain 数据`);
  logicChainData = JSON.parse(fs.readFileSync(logicChainFilePath, 'utf8'));
  console.log('已成功加载 logic-chain 数据');
} catch (error) {
  console.error('无法读取 logic-chain 数据文件:', error.message);
  process.exit(1);
}

// 读取 logic 数据
let logicData;
try {
  const logicFilePath = path.resolve('./json/logic_1742897851831.json');
  console.log(`尝试从 ${logicFilePath} 读取 logic 数据`);
  logicData = JSON.parse(fs.readFileSync(logicFilePath, 'utf8'));
  console.log('已成功加载 logic 数据');
} catch (error) {
  console.error('无法读取 logic 数据文件:', error.message);
  process.exit(1);
}

async function sendRequest() {
  try {
    console.log('开始发送请求...');

    // 合并数据
    const requestData = {
      base_info: baseInfoData,
      score: scoreData,
      correction: correctionData,
      enhancement: enhancementData,
      analyse: analyseData,
      material: materialData,
      logic_chain: logicChainData,
      logic: logicData
    };

    const response = await axios({
      method: 'post',
      url: URL, // URL 是接口地址
      data: requestData,
      responseType: 'text',
      headers: {
        'Content-Type': 'application/json'
      }
    });

    console.log(`响应状态: ${response.status}`);

    // 保存响应以便调试
    fs.writeFileSync('debug_response.txt', response.data);

    // 响应直接就是下载链接
    const downloadUrl = response.data;
    console.log(`获取下载链接成功: ${downloadUrl}`);

    // 下载 PDF
    const pdfResponse = await axios({
      method: 'get',
      url: downloadUrl,
      responseType: 'arraybuffer'
    });

    // 保存 PDF
    const filename = `report-${Date.now()}.pdf`;
    fs.writeFileSync(filename, pdfResponse.data);
    console.log(`PDF 已保存: ${filename}`);
  } catch (error) {
    console.error('请求失败:', error.message);
    if (error.response) {
      console.error('错误状态码:', error.response.status);
      console.error('错误详情:', error.response.data);
    }
  }
}

sendRequest();