> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# 文件

> 将 PDF、Word、PowerPoint、Excel、CSV、文本或图片文件上传为一个可搜索的文档，或将其解析为 Markdown 而不存储任何内容。

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

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

扫描件和图片通过 OCR 读取，无论页数多少。支持的格式：[文件类型](https://docs.conare.ai/zh/file-types.md)。

## 上传文件

`POST /namespaces/:namespace/files`

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

```bash curl theme={null}
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
```

```bash curl (form) theme={null}
curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -F file=@report.pdf
```

```bash curl (URL) theme={null}
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"}'
```

```ts TypeScript theme={null}
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" },
});
```

```json Response theme={null}
{
  "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` 等（[全部](https://docs.conare.ai/zh/file-types.md)）；否则从字节判断，再从文件名判断 |
| `user` | string | 仅限上传。文件所属的用户；删除该用户会一并删除文件 |
| `metadata` | string | 仅限上传。一个 JSON 对象，会复制到文档的元数据中 |
| `pages` | string | 要读取的页、幻灯片或帧，如 `1-20,25` 或 `5-` |
| `password` | string | 打开受保护的 PDF、Word、PowerPoint 或 Excel 文件，最大 20 MiB |
| `layout` | boolean，默认 `false` | 每个经 OCR 的部分还会带有 `blocks`：其所在页的区域（[字段](https://docs.conare.ai/zh/file-types.md#版面块)） |
| `wait` | 秒，默认 60 | 返回 `202` 前等待读取的时长，最多 300；`0` 立即响应 |

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

完整 schema：[上传文件](https://docs.conare.ai/zh/api-reference/files/upload-a-file.md)。

### 响应

| 字段 | 含义 |
| - | - |
| `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` 后可轮询此接口。

```bash curl theme={null}
curl https://api.conare.ai/namespaces/reports/files/report.pdf \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

```ts TypeScript theme={null}
const file = await reports.getFile("report.pdf");
```

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

完整 schema：[读取文件](https://docs.conare.ai/zh/api-reference/files/read-a-file.md)。

## 存储的文档

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

| 位置 | 得到什么 |
| - | - |
| [搜索](https://docs.conare.ai/zh/query.md) | 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`](https://docs.conare.ai/zh/documents#获取文档) | 用文件的 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" }` [过滤](https://docs.conare.ai/zh/filters.md) |
| 搜索单个页面 | 按 `{ "file_id": "report.pdf", "page": 3 }` 过滤 |
| 隔离用户 | 上传时带 `user`，[搜索](https://docs.conare.ai/zh/query.md)时带 `user` |
| 删除原始文件 | 原始文件会一直保留，直到命名空间或其用户被删除 |

## 解析文件

`POST /parse`

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

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

```bash curl (URL) theme={null}
curl https://api.conare.ai/parse \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'
```

```ts TypeScript theme={null}
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));
```

```json Response theme={null}
{
  "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：[解析文件](https://docs.conare.ai/zh/api-reference/parse/parse-a-file-to-markdown.md)。

### 获取解析结果

`GET /parse/:id`

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

```bash curl theme={null}
curl https://api.conare.ai/parse/prs_0e631c59528ac4f7424dc776 \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

完整 schema：[读取解析结果](https://docs.conare.ai/zh/api-reference/parse/get-a-parse-result.md)。

## 结果

| 字段 | 含义 |
| - | - |
| `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`](https://docs.conare.ai/zh/file-types#word-和-powerpoint-中的图片) |

Markdown 规则见[文件类型](https://docs.conare.ai/zh/file-types.md#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` 结束。


## Related topics

- [文件类型与 Markdown](https://docs.conare.ai/zh/file-types.md)
- [Google Cloud Storage](https://docs.conare.ai/zh/gcs.md)
- [API 概览](https://docs.conare.ai/zh/api.md)
- [Read a file](https://docs.conare.ai/zh/api-reference/files/read-a-file.md)
- [Upload a file](https://docs.conare.ai/zh/api-reference/files/upload-a-file.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.