文献检索接口

更新日期：2026-10-06。接口前缀 /api/v1/literature，所有示例与代码实现逐字段核对。

提供学术文献检索：提交中文/英文检索词，平台检索中英文学术文献库，跨库去重后返回文献条目（标题、作者、期刊、年份、DOI、摘要、链接等）。一次检索一笔固定费用，按次计费；与论文查重 / AIGC 检测共用「检测余额」账户，余额查询与说明见查重/AIGC检测接口文档。

检索为异步流程：提交订单立即返回订单号并预扣本次费用，检索完成后轮询订单详情获取完整结果；检索失败或超时自动全额退回检测余额。绝大多数订单在 1 分钟内完成，个别情况（个别检索耗时较长、平台自动重试）可能延长到几分钟，建议以 5-10 秒间隔轮询。

1. 接入信息

错误响应有两种格式：

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

2. 计费与余额

• 按次计费：一次检索订单 = 一笔固定费用，金额以下单响应的 fee_yuan 为准（平台可能调价，每笔订单按下单时的单价）
• 下单即预扣：提交订单时从检测余额全额预扣；检索失败、超时或平台无法取得结果时自动全额退回（退款后订单 fee_yuan 为 0）
• 共享余额：与查重 / AIGC 检测共用检测余额，互不隔离。余额查询 GET /api/v1/check/balance（字段说明见查重/AIGC检测接口文档），充值在平台控制台完成
• 检索正常完成即收费（即使命中 0 条）；检索失败不收费
• 平台不提供下单幂等：网络超时后重试 POST /orders 会生成新订单并再次计费，调用方应自行避免重复提交

3. 接口速览

4. 提交检索订单

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

{
  "scope": "mixed",
  "query": "大语言模型 幻觉",
  "english_query": "hallucination in large language models"
}

请求体不允许未知字段（HTTP 422）。检索词会自动去掉首尾空白。各范围使用的检索词：chinese 用 query，english 用 english_query，mixed 两者都用。

响应：

{
  "code": "success",
  "order_no": "LTR20261006153012A1B2C3",
  "status": "running",
  "fee_yuan": 0.5
}

余额不足时返回 HTTP 402 {"code": "insufficient_balance", "message": "检测余额不足，请先充值"}，订单不创建。

5. 订单详情（获取结果）

GET /api/v1/literature/orders/LTR20261006153012A1B2C3
Authorization: Bearer YOUR_API_KEY

响应（订单 completed 后出现 result 字段）：

{
  "order_no": "LTR20261006153012A1B2C3",
  "status": "completed",
  "scope": "mixed",
  "query": "大语言模型 幻觉",
  "english_query": "hallucination in large language models",
  "entry_count": 23,
  "fee_yuan": 0.5,
  "created_at": "2026-10-06 15:30:12",
  "completed_at": "2026-10-06 15:30:41",
  "fail_reason": null,
  "result": {
    "request_id": "5f0c1e2a-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "complete",
    "scope": "mixed",
    "entries": [ { "...": "文献条目，字段见下表" } ],
    "count": 23,
    "language_counts": { "zh": 12, "en": 11 }
  }
}

订单状态 status（平台状态机）：

result 内是本次检索的结果明细，其中 status 表示检索完成度（complete 全部成功 / partial 部分成功 / failed 全部失败），与订单状态是两层信息。

result 字段：

文献条目 entries[] 字段：

6. 错误码总表

订单内的失败（已建单后退回）不走上表：订单状态为 failed，费用已退，原因见 fail_reason（如检索失败、检索超时）。

7. 快速接入（Python 完整示例）

import time
import requests

BASE = "https://api.llmapi.fit"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}

# 第 1 步：提交检索订单（下单即预扣，失败自动全额退回）
resp = requests.post(f"{BASE}/api/v1/literature/orders", headers=HEADERS, json={
    "scope": "mixed",
    "query": "大语言模型 幻觉",
    "english_query": "hallucination in large language models",
    }, timeout=30).json()
order_no = resp["order_no"]

# 第 2 步：轮询订单详情，completed 后直接取 result
for _ in range(60):
    detail = requests.get(f"{BASE}/api/v1/literature/orders/{order_no}", headers=HEADERS, timeout=30).json()
    if detail["status"] != "running":
        break
    time.sleep(5)

if detail["status"] == "completed":
    for entry in detail["result"]["entries"]:
        print(entry.get("year"), entry.get("title"), entry.get("doi"))
else:
    print("检索失败（已退款）:", detail["fail_reason"])