AI写作接口

学位论文智能写作API:提交标题、字数与参考材料,平台完成材料理解、提纲、全文撰写、独立审核与Word导出;材料COS直传、结果预签名下载,按提交字数计费、失败全额退款,含结果回调。

AI 写作服务对外接口文档

更新日期:2026-11-19(首版)。接口前缀 /api/v1/writing 与 /api/v1/files,所有示例与代码实现逐字段核对。

提供学位论文智能写作:提交标题、字数与参考材料,平台完成材料理解、提纲生成、全文撰写、独立审核与文档导出,产出可直接使用的 Word 文档。文件进出全部走对象存储直链(上传用预签名 URL 直传、下载用预签名链接),调用方无需搭建文件转发。写作过程包含自主联网搜索与学术文献检索,属于写作服务的组成部分,不另收费、无需开通。

费用从「现金账户」(检测 / 文献检索 / 写作共用余额)按预扣方式收取,任务失败自动全额退还。 余额查询 GET /api/v1/check/balance,充值在平台控制台完成。

1. 接入信息

项目说明
Base URLhttps://api.llmapi.fit
认证方式Authorization: Bearer YOUR_API_KEY(与降重、查重、文献检索接口同一把密钥,控制台「APIKEY」页获取)
请求格式JSON
响应格式JSON

错误响应有两种格式:

  • 业务错误(HTTP 非 2xx):{"code": "错误码", "message": "错误说明"},错误码总表见第 9 节
  • 鉴权失败(HTTP 401):{"detail": "无效的接口密钥或登录凭证"}(无 code 字段)

2. 计费与账户

  • 按提交字数计费:费用 = ceil(target_words / 1000) × 单价 × (1 - 优惠幅度),单价以提交时平台单价为准(元/千字);平台若设有优惠,按折后金额预扣(无优惠时即原价),实际金额以建单返回的 fee 为准
  • 提交即预扣:建单成功时从现金账户全额预扣;任务失败(含各阶段超时)自动全额退回
  • 成稿实际字数不参与结算:实际字数在订单详情与结果回调中返回,仅供核对
  • 提交时余额不足返回 HTTP 402,任务不会创建
  • 平台不提供建单幂等:网络超时后重试提交会生成新订单并再次预扣费用,调用方应自行避免重复提交

3. 调用步骤(必读)

写作是异步任务接口,按下述顺序调用(前两步仅带文件材料时需要):

①(仅带文件材料时)申请上传签名 → ② 直传文件
        ↓
③ 提交写作任务(拿 order_no,费用同时预扣)
        ↓
④ 等待生成:接收结果回调(标准方式);详情接口仅作兜底查询
        ↓
⑤ 任务完成:用回调/详情里的 doc_url 下载 Word 文档

最简调用(无材料,两步接入):

  1. POST /api/v1/writing/orders 提交任务(标题 + 目标字数即可,建议同时传 callback_url),返回 order_no
  2. 等待结果回调推送终态;未配置回调时以低频轮询 GET /api/v1/writing/orders/{order_no} 兜底(限流规则见下);status=COMPLETED 后从 doc_url 下载成稿

带文件材料(在提交前增加两步):

  1. POST /api/v1/files/presign 申请上传签名,拿到 file_id 与 upload_url
  2. PUT {upload_url} 直传文件(10 分钟内有效)
  3. 提交任务时在 materials 数组中用 file_id 引用(纯文本材料跳过 1-2,直接用 text 直传)

等待结果:以回调为准,不接受以轮询代替监听

  • 结果回调是获取结果的标准方式:提交时传 callback_url,任务到达终态(成功或失败)平台主动推送(见第 8 节)。生产接入应配置回调并以其为准,不要通过高频轮询详情接口来监听任务进度
  • 详情接口仅作兜底查询:适用于回调未送达、核对结果、排查问题、偶尔查看进度等场景;生成通常耗时数十分钟至数小时,高频查询不会加快生成
  • 轮询限流(必须遵守):同一 API Key × 同一订单 10 秒内仅允许查询 1 次,超频返回 HTTP 429(带 Retry-After: 10 响应头);确需轮询兜底时建议 1-5 分钟查询 1 次

下载链接 24 小时有效,过期后重查详情接口即自动重签新链接。

4. 接口速览

方法路径说明鉴权
POST/api/v1/files/presign申请材料上传预签名 URL(通用文件接口)需要
PUT{upload_url}直传材料文件到对象存储(地址为 5.1 接口返回的 upload_url)不需要(URL 自带签名,10 分钟有效)
POST/api/v1/writing/orders提交写作任务需要
GET/api/v1/writing/orders/{order_no}任务详情(进度 / 结果下载链接)需要

5. 上传材料(预签名直传)

文件材料先上传到平台文件存储(腾讯云 COS 对象存储),再在提交任务时以 file_id 引用,流程如下:

① 申请上传链接                       ② 直传文件到 COS                 ③ 提交任务时引用
POST /api/v1/files/presign    →     PUT {upload_url}          →     materials: [
携带 scene / filename / size         请求体为文件二进制                  { "file_id": "uf_...", "category": "..." }
返回 file_id 与 upload_url           地址自带签名,无需鉴权头           ]
(upload_url 有效期 10 分钟)         成功返回 HTTP 200

纯文本材料不走本节,提交任务时直接携带 text 字段(见 6.2)。

5.1 申请上传链接

POST /api/v1/files/presign
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{ "scene": "writing", "filename": "开题报告.docx", "size": 1234567 }
字段类型必填说明
scenestring是业务场景,写作材料固定传 writing
filenamestring是文件名(含扩展名)。支持 docx / doc / pdf / xlsx / txt 五种格式
sizestring/number是文件大小(字节),单文件不超过 5MB

响应:

{
  "file_id": "uf_3f9c2a81b04d5e7f1902",
  "upload_url": "https://llmapi-documents-1256020686.cos.ap-guangzhou.myqcloud.com/writing/materials/uf_.../开题报告.docx?q-sign-algorithm=...",
  "expires_in": 600
}
字段说明
file_id文件 ID,提交写作任务时引用
upload_urlCOS 临时上传地址,expires_in 秒内有效(600 = 10 分钟)

5.2 直传文件

PUT {upload_url}
Content-Type: application/octet-stream

<文件二进制内容>

文件内容原样作为请求体发送:

# Python requests
import requests

with open("开题报告.docx", "rb") as f:
    resp = requests.put(
        upload_url,
        data=f.read(),
        headers={"Content-Type": "application/octet-stream"},
    )
print(resp.status_code)  # 200 即上传完成

返回 HTTP 200 即上传完成,无需向平台确认;提交任务时平台会校验文件已上传。实际上传大小必须与 5.1 申请时声明的 size 一致,不一致会被对象存储直接拒绝(HTTP 403)——申请时须如实申报文件大小。

6. 提交写作任务

POST /api/v1/writing/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "title": "基于深度学习的XX研究",
  "genre": "thesis",
  "subject": "计算机科学",
  "target_words": 10000,
  "outline_depth": 3,
  "materials": [
    { "file_id": "uf_3f9c2a81b04d5e7f1902", "category": "proposal" },
    { "file_id": "uf_88d1f0aa12bc34de5678", "category": "survey_data" },
    { "category": "references", "name": "导师指定文献", "text": "张三. 深度学习在XX中的应用[J]. ..." }
  ],
  "callback_url": "https://client.example.com/writing/callback"
}

6.1 任务参数

字段类型必填说明
titlestring是论文标题,不超过 120 字
genrestring否体裁,当前仅支持 thesis(论文,默认值),传其他值返回 422
subjectstring否学科(如「计算机科学」);不传由平台在提纲阶段自动识别
target_wordsnumber否目标字数,3000–100000,默认 10000。计费按该值计算
outline_depthnumber否提纲层级数,0/1/2/3/4,默认 0。0=层级数由平台按学科与篇幅自动确定;1=只要一级大纲(仅到章);2=要二级大纲(章、节);3=三级大纲(章、节、小节);4=四级大纲
materialsarray否参考材料,可省略。每个分类每单仅一份,proposal 与 outline 互斥,故每单最多 5 份
callback_urlstring否结果回调地址(见第 8 节);不传则只能轮询详情接口

6.2 材料两种形态(逐份二选一,可混用)

引用已上传文件:{ "file_id": "uf_...", "category": "开题报告类" }

直传文本:{ "category": "references", "name": "文献清单", "text": "纯文本或 Markdown 内容" }

  • text 必填、非空、不超过 5 万字符;纯文本与 Markdown 均按原文保存
  • name 可省略,缺省为 {category}-text-{序号}
category 值含义写作中的用途
proposal开题报告论文结构须遵循其研究思路与要求;与 outline 互斥,同单不能同时提供
outline大纲提供即跳过提纲生成,大纲原样作为提纲直接开工;与 proposal 互斥,同单不能同时提供
survey_data调研数据论证数据来源
experiment_data实验数据论证数据来源
references参考文献成稿参考文献以此清单为基础,平台按写作需要自动判断是否补充检索
other其他材料参考素材

6.3 响应

{
  "order_no": "W20261119153012A1B2C3",
  "status": "CREATED",
  "fee": 100.0
}
字段说明
order_no平台订单号(W 前缀),后续查询与回调均以此定位
statusCREATED(已建单,准备执行)
fee本单费用(元,按提交字数计算)

7. 任务详情

GET /api/v1/writing/orders/W20261119153012A1B2C3
Authorization: Bearer YOUR_API_KEY

本接口是兜底查询接口,不作为任务监听手段:任务进度与终态结果以结果回调(第 8 节)为准,请勿以高频轮询代替回调监听。限流:同一密钥 × 同一订单 10 秒内仅允许查询 1 次,超频返回 HTTP 429 并带 Retry-After: 10 响应头。

进行中响应:

{
  "order_no": "W20261119153012A1B2C3",
  "status": "PROCESSING",
  "phase": "writing",
  "created_at": "2026-11-19 15:30:12"
}
字段说明
statusCREATED(已建单待执行)/ PROCESSING(生成中)/ COMPLETED(已完成)/ FAILED(已失败)
phase阶段细分:queued 待启动 → extracting 材料理解 → outlining 提纲生成 → writing 正文撰写 → reviewing 独立审核 → exporting 导出

完成响应(追加字段):

{
  "status": "COMPLETED",
  "word_count": 9820,
  "doc_url": "https://...预签名下载链接...",
  "doc_url_expires_at": "2026-11-20T16:00:00",
  "fee": 100.0,
  "notify_status": "SUCCESS",
  "completed_at": "2026-11-19 17:02:44"
}
字段说明
word_count成稿实际字数(仅供核对,不参与计费)
doc_url结果文档下载链接(Word 文档),24 小时有效;链接过期后重查本接口即自动重签
fee本单费用(元)

失败响应(追加字段):

{
  "status": "FAILED",
  "error_code": "TIMEOUT",
  "error_message": "生成超时,费用已全额退还",
  "refund": 100.0,
  "completed_at": "2026-11-19 17:02:44"
}
字段说明
error_codeTIMEOUT(生成超时)/ GENERATION_FAILED(生成失败)
refund已退还金额(元),失败一律全额退款

生成时长:通常数十分钟至数小时(与字数相关)。各阶段均有超时保护,任一阶段超时即判失败并全额退款;其中正文阶段(撰写、审核、导出全程)的保护时限为 200 分钟。

8. 结果回调

任务到达终态时,平台向 callback_url 推送结果(POST JSON):

  • 请求头:X-Timestamp(Unix 秒)、X-Signature = HMAC-SHA256(调用方 API_KEY, "{timestamp}\n{body}")——验签方式与查重接口回调完全一致
  • 成功判定:必须显式返回 HTTP 200;其余任何状态码、连接失败、15 秒超时均视为推送失败
  • 失败后按 60s / 5min / 30min / 1h / 6h 间隔重试 5 次(共 6 次),任一次收到 200 即停止;达到次数后不再推送,结果仍可经详情接口获取

推送数据为单一结构:成功与失败字段完全一致(以 status 区分终态),全部字段恒在,不适用时置 null / 0——调用方只需维护一套解析逻辑:

字段说明
order_no平台订单号
status终态:COMPLETED(成功)/ FAILED(失败)
error_code失败原因码:TIMEOUT(生成超时)/ GENERATION_FAILED(生成失败);成功时为 null
message结果描述:成功为「生成完成」;失败为原因说明(均含费用处理结果)
word_count成稿实际字数(不参与计费,仅供核对);失败时为 null
doc_url结果文档下载链接(Word 文档,24 小时有效);失败时为 null。链接过期后重查详情接口即自动重签
fee本单费用(元,按提交字数计算)
refund退款金额(元):成功为 0,失败为全额退款
completed_at终态时间(ISO 8601)

成功示例:

{
  "order_no": "W20261119153012A1B2C3",
  "status": "COMPLETED",
  "error_code": null,
  "message": "生成完成",
  "word_count": 9820,
  "doc_url": "https://...预签名下载链接(24h)...",
  "fee": 100.0,
  "refund": 0.0,
  "completed_at": "2026-11-19T17:02:44"
}

失败示例:

{
  "order_no": "W20261119153012A1B2C3",
  "status": "FAILED",
  "error_code": "GENERATION_FAILED",
  "message": "生成失败,费用已全额退还",
  "word_count": null,
  "doc_url": null,
  "fee": 100.0,
  "refund": 100.0,
  "completed_at": "2026-11-19T17:02:44"
}

9. 错误码总表

HTTPcode场景
401unauthorized(detail 格式)API Key 无效
402insufficient_balance现金账户余额不足(任务不创建)
404order_not_found / file_not_found订单或文件不存在 / 不属于该调用方
422invalid_scene / bad_format / file_too_large上传签名:场景、格式(docx/doc/pdf/xlsx/txt)、大小(≤5MB)校验失败
422file_not_uploaded提交任务时引用的文件尚未上传完成
422invalid_category / invalid_material / text_too_long / invalid_text / conflicting_materials / duplicate_category材料分类非法 / 每份材料 file_id 与 text 须二选一 / 文本超 5 万字符 / 文本为空或含非法字符 / proposal 与 outline 同单同时提供 / 同一分类提交多份
422invalid_genre / invalid_title / invalid_subject / invalid_target_words / invalid_outline_depth / invalid_callback_url / too_many_materials任务参数校验失败
429rate_limited详情查询超频(10 秒 1 次,见 Retry-After 响应头)
503storage_unavailable文件存储暂不可用,请稍后重试

10. 注意事项清单

接入前请逐条确认,均为容易踩坑的硬性规则:

#注意事项
1文件材料仅支持 docx / doc / pdf / xlsx / txt 五种格式,其他格式(如 .wps)在申请上传链接时即被拒绝
2单文件大小 不超过 5MB;申请上传链接时申报的 size 必须与文件实际大小一致,不一致时直传被对象存储拒绝(HTTP 403)
3上传链接 10 分钟内有效,过期需重新申请(file_id 会变化)
4直传文本材料单份 不超过 5 万字符,含 NUL 字符(空字节)拒收;纯文本与 Markdown 均按原文保存
5每单材料 最多 5 份:每个分类仅一份、开题报告(proposal)与大纲(outline)互斥,违反分别返回 422 duplicate_category / conflicting_materials
6提供参考文献(references)时,成稿参考文献以此清单为基础,平台按写作需要自动判断是否补充检索
7平台不提供建单幂等:网络超时后重试提交会生成新订单并再次预扣费用,调用方须自行避免重复提交
8费用按提交字数计算(不足一千字进位),成稿实际字数不参与结算;余额不足返回 402 且任务不创建
9等待结果以回调为准,不要以轮询代替监听:详情接口同一密钥 × 同一订单 10 秒仅可查询 1 次,超频返回 429
10回调处理成功必须显式返回 HTTP 200,其余任何状态码均视为推送失败并触发重试(共 6 次后停推)
11下载链接 24 小时有效,过期后重查详情接口自动重签,可随时重新获取