文件 - Conare

两个路由使用同一个解析器读取文件，选项和结果都相同：

路由	作用	大小
`POST /namespaces/:namespace/files`	将文件存储为一个可搜索的文档；搜索会指出回答所在的页、幻灯片或行	最大 512 MiB 和 5,000 页
`POST /parse`	以 Markdown 返回文件，不存储任何内容	最大 20 MiB

扫描件和图片通过 OCR 读取，无论页数多少。支持的格式：文件类型。

上传文件

POST /namespaces/:namespace/files 将文件字节作为请求体发送，或作为 multipart 表单的文件部分发送，或发送 JSON {"url": "https://..."} 让 Conare 获取文件。

curl "https://api.conare.ai/namespaces/reports/files?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -F file=@report.pdf

curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import { readFile } from "node:fs/promises";

const reports = conare.namespace("reports");
const file = await reports.uploadFile(await readFile("report.pdf"), "report.pdf", {
  metadata: { site: "north-pit" },
});

Response

{
  "file_id": "report.pdf",
  "name": "report.pdf",
  "type": "pdf",
  "state": "ready",
  "source_id": "src_01139ca8ca59f2556f65b60e",
  "uploaded_at": 1792618822534,
  "pages": 2,
  "ids": ["src_01139ca8ca59f2556f65b60e:report.pdf"],
  "ocr_failed": [],
  "ocr_pending": [],
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}

响应最多等待 wait 秒以完成文件读取：文件为 ready 或 failed 时返回 200，仍在读取时返回 202。

选项

查询参数，除注明外两个路由均适用。

选项	类型	作用
`name`	string	文件名，最多 4,096 个字符；其扩展名用于区分 `.csv`、`.tsv`、`.md` 与普通文本
`id`	string	仅限上传。文件的 id，即其文档 id 的末尾部分；默认为 `name`，其他字符替换为 `-`
`type`	string	`pdf`、`docx`、`pptx`、`xlsx`、`csv`、`png` 等（全部）；否则从字节判断，再从文件名判断
`user`	string	仅限上传。文件所属的用户；删除该用户会一并删除文件
`metadata`	string	仅限上传。一个 JSON 对象，会复制到文档的元数据中
`pages`	string	要读取的页、幻灯片或帧，如 `1-20,25` 或 `5-`
`password`	string	打开受保护的 PDF、Word、PowerPoint 或 Excel 文件，最大 20 MiB
`layout`	boolean，默认 `false`	每个经 OCR 的部分还会带有 `blocks`：其所在页的区域（字段）
`wait`	秒，默认 60	返回 `202` 前等待读取的时长，最多 300；`0` 立即响应

application/pdf 等 Content-Type 也可声明类型。
wait：true 等于 60；响应总会在 105 秒内返回。上传时，false 在文本存储后即响应，并附带 ocr_pending。
pages 之外的页不会被读取或 OCR；对没有页的文件使用 pages 会返回 400。

完整 schema：上传文件。

响应

字段	含义
`file_id`、`name`、`type`	使用的 id、文件名以及读取到的类型（所有图片格式均为 `image`）
`state`	`queued`、`parsing`、`ocr`（OCR 仍在读取 `ocr_pending`）、`ready`，或带 `error` 的 `failed`
`source_id`	命名空间的文件数据源；文档 id 以它开头
`ids`	文件唯一的文档 `["<source_id>:<file_id>"]`，在 `ready` 后提供
`uploaded_at`	Unix 毫秒时间戳
`result`	若之前上传过相同的文件、名称、元数据和选项，则为 `unchanged`；不会重新读取
`pages`	PDF 的页数或图片的帧数
`ocr_failed`	多次尝试后 OCR 仍无法读取的页；重新上传即可重试
`markdown`、`parts`、`without_text`	结果

images_without_text、pages_without_text、pages_ocr、images_ocr、sheets、slides 和 slides_without_text 已弃用：parts 和 without_text 提供相同信息。

查看文件

GET /namespaces/:namespace/files/:id 返回该文件的最新上传，字段相同；收到 202 后可轮询此接口。

curl https://api.conare.ai/namespaces/reports/files/report.pdf \
  -H "Authorization: Bearer $CONARE_API_KEY"

const file = await reports.getFile("report.pdf");

选项	类型	作用
`user`	string	用户，适用于带 `user` 上传的文件

完整 schema：读取文件。

存储的文档

一个文件就是一个文档，<source_id>:<file_id>；它的页、幻灯片、工作表行、章节和图片是它的各个部分。

位置	得到什么
搜索	PDF 或图片的一页、一张幻灯片或工作表的一个行范围各自作为一个结果，id 为 `<source_id>:<file_id>$<part>`：`$page-3`, `$slide-4`, `$<sheet>-1`
在文本、Markdown 或 Word 文件中搜索	一个结果，即文件 `<source_id>:<file_id>`，附带其中任意位置的段落
结果的 `metadata`	其部分或第一个段落所在的位置，键见下表
`GET /namespaces/:namespace/documents/:id`	用文件的 id 得到整个文件的文本，页与页之间有一个空行；用某个部分的 id 只得到该部分

部分所在的位置

文件	元数据中的位置
PDF	`page`
Word、文本、Markdown	`part`、`heading`，文本还有 `lines`
PowerPoint	`slide`
Excel、CSV、TSV	`sheet`、`rows`
图片	`page` 和 `frame`
Word 中的图片	`image`、`heading`
幻灯片中的图片	`slide`、`image`
工作表中的图表	`sheet`

该文档还包含 file、file_id、file_type、uploaded_at、上传时的 metadata，以及经 OCR 读取时的 ocr: true。较早上传的文件可能仍是每个部分一个文档，例如 <source_id>:<file_id>:page-1，直到重新上传。

目的	做法
替换文件	使用相同 id 重新上传
安全重试	相同的文件、名称、元数据和选项会返回 `unchanged`，无需 `Idempotency-Key`
搜索单个文件	按 `{ "file_id": "report.pdf" }` 过滤
搜索单个页面	按 `{ "file_id": "report.pdf", "page": 3 }` 过滤
隔离用户	上传时带 `user`，搜索时带 `user`
删除原始文件	原始文件会一直保留，直到命名空间或其用户被删除

解析文件

POST /parse 以 Markdown 返回文件，不存储任何内容；任何密钥都可解析，包括 Models only 密钥。

curl "https://api.conare.ai/parse?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl https://api.conare.ai/parse \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import { readFile } from "node:fs/promises";

const out = await conare.parse(await readFile("report.pdf"), { name: "report.pdf" });
if (out.state === "parsing") console.log(await conare.getParse(out.id));

Response

{
  "id": "prs_76149e8db2be257fa8a0ac01",
  "state": "done",
  "type": "pdf",
  "name": "report.pdf",
  "pages": 2,
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}

选项	类型	作用
`url`	string	在 JSON 请求体中：公共地址上的 `https` URL，需在 60 秒内获取完成，最大 20 MiB
`name`、`type`、`pages`、`password`、`layout`、`wait`		与上传相同

请求体最大 20 MiB，OCR 最多读取 100 页；之后的页保留其文本层。
要解析 JSON 文件，请以 text/plain 发送。

完整 schema：解析文件。

获取解析结果

GET /parse/:id 返回 202（state: "parsing"）的解析结果会保留 24 小时：持续获取，直到 state 为 done，或为带 error 的 failed。

curl

curl https://api.conare.ai/parse/prs_0e631c59528ac4f7424dc776 \
  -H "Authorization: Bearer $CONARE_API_KEY"

完整 schema：读取解析结果。

结果

字段	含义
`markdown`	整个文件；每页、每张幻灯片和每个工作表以 `<!-- page 3 -->`、`<!-- slide 4 -->` 或 `<!-- sheet "Q3" -->` 开头
`parts`	按阅读顺序排列，每项包含 `locator`、`markdown`、`ocr` 和 `confidence`
`parts[].locator`	`{"page": 3}`、`{"slide": 4, "image": 1}`、`{"sheet": "Q3", "rows": "2-41"}` 或 `{"part": 2, "heading": "..."}`
`parts[].ocr`	由 OCR 从页面图像读取，而非从文本层读取
`parts[].confidence`	OCR 的置信度，0 到 1；OCR 未提供时为 `null`（多数原生数字页面）
`without_text`	不含文本的 `pages`、`slides` 和 `images`，每张图片附带其 `reason`

Markdown 规则见文件类型。

错误

错误	场景
`400 invalid_request`	选项无效：对没有页的文件使用 `pages`、`wait` 超过 300、`metadata` 不是 JSON 对象、URL 不是公共地址上的 `https`
`400 fetch_failed`	URL 未以 `200` 返回文件
`404 parse_not_found`	过去 24 小时内没有该 id 且返回 `202` 的解析
`409 file_replaced`	等待响应期间文件被删除
`409 user_purging`	该用户正在被删除
`413 payload_too_large`	超过 512 MiB（上传）或 20 MiB（解析，或带 `password`）
`415 unsupported_file`	不是支持的类型，或与声明的 `type` 不符；消息会说明应另存为何种格式
`422 password_protected`	文件有密码：请通过 `password` 发送
`422 unreadable_file`	文件已损坏
`422 no_text`	没有任何页、工作表、幻灯片、段落或图片包含文本
`503 files_unavailable`	当前无法存储文件；请稍后重试

超过 5,000 页、工作表或幻灯片的文件最终会以 failed 和 too_large 结束。

快速开始

核心

文件

同步

模型

工具

文件

上传文件

选项

响应

查看文件

存储的文档

部分所在的位置

解析文件

获取解析结果

结果

错误

​上传文件

​选项

​响应

​查看文件

​存储的文档

​部分所在的位置

​解析文件

​获取解析结果

​结果

​错误

上传文件

选项

响应

查看文件

存储的文档

部分所在的位置

解析文件

获取解析结果

结果

错误