论文相关接口

Base：NEXT_PUBLIC_API_URL / LLMWIKI_BASE_URL（本地 http://localhost:8000）。
鉴权：Authorization: Bearer <token>（登录 JWT 或 sv_ 密钥）。

场景与 Node 示例见 论文对接 · 场景示例。

创建任务文献库（幂等）

与 空间 · 创建 同一接口：POST /v1/knowledge-bases，带上 external_task_id。

POST /v1/knowledge-bases
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "论文任务-大模型评测",
  "external_task_id": "lp_task_abc123",
  "description": "可选"
}

响应：空间对象本身。新建 201，复用 200。请持久化 id 与 slug。

兼容旧路径 POST /v1/integrations/paper/task-libraries（返回 { created, knowledge_base }）。

写入文献（上传 / 导入）

与 上传文件 共用：

参考文献短索引

GET /v1/knowledge-bases/{kb_id}/reference-index
Authorization: Bearer <token>

可选查询参数 variants（默认 source,preview），与下方「获取文件地址」相同。

返回参考文献短列表（编号、标题、预签名 URL 等），供引用表或 HTTP 回退时挑条注入写作 prompt。

{
  "knowledge_base_id": "...",
  "count": 35,
  "variants": ["source", "preview"],
  "items": [
    {
      "index": 1,
      "document_id": "...",
      "title": "…",
      "citation": "[1] 标题。作者。期刊，2024。 DOI: …",
      "external_id": "ref_1",
      "doi": "10.1000/xyz",
      "file_type": "md",
      "status": "ready",
      "urls": { "source": null, "preview": null }
    },
    {
      "index": 2,
      "document_id": "...",
      "title": "…",
      "citation": "[2] …",
      "external_id": "ref_2",
      "doi": null,
      "file_type": "pdf",
      "status": "ready",
      "urls": { "source": "https://…", "preview": "https://…" }
    }
  ]
}

• 预签名默认约 1 小时有效；无对象或 Markdown 参考文献无存储文件时对应值为 null（上例 md 条目属正常）。
• 未配置对象存储时 urls 各 variant 均为 null。
• 其它取值见下方「获取文件地址」/ 文档 · 单篇 URL：converted、tagged、ocr。

获取文件地址（批量）

按任务 external_task_id 一次返回任务文献库内各文档的预签名 URL：

GET /v1/integrations/paper/task-libraries/by-external/{external_task_id}/files?variants=source,preview
Authorization: Bearer <token>

等价（已有 kb_id 时）：

GET /v1/knowledge-bases/{kb_id}/files?variants=source,preview
Authorization: Bearer <token>

响应（节选）

{
  "knowledge_base_id": "...",
  "external_task_id": "lp_task_abc123",
  "count": 2,
  "variants": ["source", "preview"],
  "items": [
    {
      "document_id": "...",
      "filename": "paper.pdf",
      "file_type": "pdf",
      "status": "ready",
      "external_id": "ref_1",
      "has_content": true,
      "urls": { "source": "https://…", "preview": "https://…" }
    }
  ]
}

• 预签名默认约 1 小时有效。
• 某 variant 无对象时值为 null（不导致整请求失败）。
• 导入的 Markdown 参考文献通常无存储文件：urls 可能全 null，用 GET /v1/documents/{id}/content；has_content 标明是否有正文。

单篇见 文档 · 获取文件地址（单篇）。

同步文档到知识库

对接方在用户勾选「同步到知识库」后调用。你只需传 目标知识库 id 与 源文档 id；Textira 会完成拷贝，不要先拉 /files 再自行上传。

前置条件：

• 目标库 kind 必须为 knowledge（不能是任务文献库）
• 源文档与 Token 属同一用户
• 源文档 status 不能是 pending / processing（未就绪会 409，稍后重试）

请求

POST /v1/knowledge-bases/{targetKbId}/documents/import
Authorization: Bearer <token>
Content-Type: application/json

{
  "sourceDocumentId": "<task-lib-doc-uuid>",
  "directory": "/",
  "tags": ["论文同步"],
  "duplicateStrategy": "reuse"
}

同一 sourceDocumentId 再同步：reuse 返回已有文档（200）；reject 返回 409。

成功响应

新建 201，已存在且 reuse 时 200：

{
  "source_document_id": "...",
  "knowledge_document_id": "...",
  "target_knowledge_base_id": "...",
  "status": "completed",
  "duplicate": false,
  "has_binary": true
}

批量

POST /v1/knowledge-bases/{targetKbId}/documents/import-batch
Authorization: Bearer <token>
Content-Type: application/json

{
  "sourceDocumentIds": ["…", "…"],
  "directory": "/papers/",
  "duplicateStrategy": "reuse"
}

响应含 completed / already_exists / failed 与逐条 results。单次最多 100 条；单条失败不中断整批。

错误码

接入步骤

1. UI 勾选 → 准备好源 document_id 与目标知识库 id
2. POST …/documents/import，body 至少 { "sourceDocumentId": "…" }
3. 保存返回的 knowledge_document_id（含 duplicate: true）
4. 收到「仍在解析」类 409 则稍后重试

按大纲生成插图

POST /v1/integrations/paper/figures：提交论文大纲，Textira 判断需要哪些图并异步出图。轮询 GET …/figures/{id} 直到 succeeded，用 figures[].url 打开图片，用 slot 插入对应章节。

outline 必填，文字或 JSON 均可（章节标题 + 要点即可）。不必传 plotting_plan / plot_type。materials.idea、materials.experimental_log 可选；没有实测数字时只出方法示意图。有样品或装置时可能再补 0–2 张组图（一张 PNG，A/B/C 拼版）。

POST /v1/integrations/paper/figures
Authorization: Bearer <token>
Content-Type: application/json

{
  "locale": "zh",
  "outline": "1 引言\n2 方法：双塔检索与重排序\n3 实验设计与评价指标",
  "materials": {
    "idea": "可选。方法简述，有则更准",
    "experimental_log": "可选。有实测数字才会规划数据图"
  }
}

outline 也可以是章节 JSON（标题、小节、要点），结构不限。

一次最多 8 张。同一用户最多 2 个进行中的任务。大纲为空会 400。

响应 202：status 为 queued，此时 figures 可能仍是空数组（还在判断画什么）。轮询：

GET /v1/integrations/paper/figures/{id}
Authorization: Bearer <token>

status：queued → running → succeeded / failed。成功后 figures[].url 可在浏览器打开（约 1 小时有效，请重新 GET 再开）。slot / plot_type 是 Textira 判定的结果，按 slot 放到章节即可。

{
  "id": "…",
  "status": "succeeded",
  "figures": [
    {
      "figure_id": "fig_method",
      "slot": "METHOD",
      "caption": "方法流程。展示模块关系",
      "title": "方法流程",
      "plot_type": "diagram",
      "url": "https://textira.com/v1/storage/…/fig_method.png?…"
    }
  ]
}

出图需要数分钟。请轮询，不要把 POST 当同步接口。

文案出图

POST /v1/integrations/figures：与实验里 @绘图 相同，用一段文案生成一张图。一次请求等到画完，响应里就是 figures[].url（约 1 小时有效）。

按论文大纲一次出多张图，仍用上面的 POST /v1/integrations/paper/figures。

POST /v1/integrations/figures
Authorization: Bearer <token>
Content-Type: application/json

{
  "locale": "zh",
  "kind": "chart",
  "prompt": "ROC"
}

文案为空且没有表会 400。photo / viewport 必须写清拍什么。出图失败 502。

响应 200：

{
  "kind": "chart",
  "prompt": "ROC",
  "figures": [
    {
      "figure_id": "fig_1",
      "caption": "ROC",
      "mime": "image/png",
      "url": "https://textira.com/v1/storage/…/fig_1.png?…"
    }
  ]
}

流程图：

{
  "kind": "schematic",
  "prompt": "CONSORT：筛选 500，排除 150，随机 350"
}

带表：

{
  "kind": "chart",
  "prompt": "柱状图",
  "attachments": [
    {
      "name": "scores.csv",
      "mime": "text/csv",
      "data": "<base64>"
    }
  ]
}

生成论文草稿

POST /v1/integrations/paper/drafts：提交题目、选题和模板。先设计实验，再按该设计写正文。立刻返回 id。轮询 GET …/drafts/{id} 直到 succeeded，用 manuscript.markdown 渲染整篇论文。失败后对同一 id 再 POST …/drafts/{id} 即可继续。

title、topic、template_id 必填。template_id 是期刊或学位论文版式。这本期刊若已绑定写作大纲，正文按那份大纲的章节写；没有绑定就按默认章节写。成功后 manuscript.markdown 是整篇论文。不再另写一份交付稿，delivery 为空。instruction 可选，只作补充说明，不触发第二次改写。规范不要写进 topic。

POST /v1/integrations/paper/drafts
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "miR-21 in hepatocellular carcinoma",
  "topic": "miR-21 调控肝癌细胞迁移",
  "template_id": "zh-nmj",
  "instruction": "摘要 500–800 字，单独成段……（调用方写作规范全文）"
}

同一用户最多 2 个进行中的草稿。缺字段或 template_id 不认识会 400。额度不足返回 402。

响应 202：status 为 queued，此时 manuscript 为 null。保存 id 去查询。响应头带 Retry-After: 15。

{
  "id": "…",
  "status": "queued",
  "stage": "design",
  "stage_label": "正在设计实验",
  "template_id": "zh-nmj",
  "title": "…",
  "manuscript": null,
  "delivery": null,
  "error": null
}

轮询：

GET /v1/integrations/paper/drafts/{id}
Authorization: Bearer <token>

列出当前账号下的草稿（进行中的排前面）：GET /v1/integrations/paper/drafts。同一时间最多 2 个进行中。

status：queued → running → succeeded / failed。stage 依次为 design（正在设计实验）、write（正在写正文）、done（已完成）。进行中 manuscript 为 null。建议每 10–30 秒 GET 一次，不要把 POST 当同步接口。全程可能数分钟到数十分钟。

成功后同一形状。manuscript.markdown 是整篇论文：

{
  "id": "…",
  "status": "succeeded",
  "stage": "done",
  "stage_label": "已完成",
  "template_id": "zh-nmj",
  "title": "…",
  "manuscript": {
    "title": "miR-21 与肝癌",
    "markdown": "# miR-21 与肝癌\n\n## 摘要\n\n目的……\n\n## 关键词\n\n微小RNA-21；肝细胞癌\n\n## 前言\n\n……\n\n## 1 资料与方法\n\n……\n\n### 1.1 研究对象\n\n……\n\n## 2 结果\n\n……\n\n## 参考文献\n\n1. ……"
  },
  "delivery": null,
  "error": null
}

前端把 markdown 交给 Markdown 渲染即可。这份 Markdown 由成稿 LaTeX 转出：章节是标题，表格是 Markdown 表格，插图是 ![图注](http://<API>/v1/paper-tasks/<paper_task_id>/assets/figures/<文件名>)。delivery 恒为 null。

失败时 error 为 { "code": "design_failed" | "write_failed", "message": "…" }。对同一 id 再 POST 即可继续（无需 body），仍用这个 id 轮询。正文已经写出时，继续会直接返回这份 manuscript：

POST /v1/integrations/paper/drafts/{id}
Authorization: Bearer <token>

响应同创建：202，status 为 queued。已完成的任务再 POST 会直接返回正文。额度不足仍为 402。

流程是：按题目和选题设计实验（对照、指标、方案），再按该设计写方法与结果。

选模板 + Markdown → PDF / Word

选一个期刊或学位论文模板，提交 Markdown，用 format 选择 PDF 或 Word。不必先创建稿件。鉴权与其它接口相同（登录 JWT 或 sv_ 密钥）。

列出模板

GET /v1/render/templates
Authorization: Bearer <token>

用返回的 id 作为 template_id。中文稿请选 lang 为 zh 的模板，英文稿选 en。当前可用模板如下。

英文会议 / 期刊

中文刊 / 通用学科

学位论文

生成 PDF 或 Word

POST /v1/render
Authorization: Bearer <token>
Content-Type: application/json

{
  "template_id": "zh-jos",
  "format": "pdf",
  "markdown": "# 题目\n\n## 引言\n\n正文……\n"
}

成功：200，响应体就是文件。format=pdf 时为 PDF，format=docx 时为 Word。
失败：400 模板不存在、正文为空，或中文稿选了英文模板；413 正文过长；503 Word 暂时无法生成；500 生成失败（原因在 JSON 的 detail 里）。

Markdown → PPT

选一个演示稿模板，提交 Markdown，得到 PowerPoint。

列出演示稿模板

GET /v1/render/slides/templates
Authorization: Bearer <token>

用返回的 id 作为 template_id。

生成 PPT

POST /v1/render/slides
Authorization: Bearer <token>
Content-Type: application/json

{
  "template_id": "academic-paper",
  "markdown": "# 题目\n\n## 背景\n\n……\n\n## 方法\n\n……\n\n## 结论\n\n……\n"
}

成功：200，响应体就是 .pptx 文件。
失败：400 模板不存在或正文为空；413 正文过长；503 暂时无法生成；500 生成失败（原因在 JSON 的 detail 里）。

删除稿件

DELETE /v1/paper-tasks/{task_id}
Authorization: Bearer <token>

仅任务所有者可删。会先停止仍在生成/精修的进程，再删除数据库行（版本、分享链接级联删除）以及磁盘上的任务目录。成功返回 204，无响应体。不存在或不属于当前用户返回 404。

相关：HTTP API 总览 · 论文对接 · 场景示例 · 文档