Paper endpoints

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 当同步接口。

选模板 + 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 总览 · 论文对接 · 场景示例 · 文档