插件

插件在模型调用前后处理请求或响应，让模型可以使用经过转换的输入。它们不会改变模型本身的原生能力。file-parser 是第一个插件：在需要时，把文档或图片转换为文字，再交给你选择的模型。

同一套 plugins 参数适用于 /model/v1/chat/completions、/model/v1/messages 和 /model/v1/responses 的创建请求，支持流式和非流式。参数由平台消费，不会作为模型参数传给上游。

配置与默认行为

在请求体中加入 plugins 数组，每个配置用 id 指定插件：

{
  "plugins": [
    { "id": "file-parser", "enabled": true }
  ]
}

未传 plugins 或传 plugins: [] 都表示沿用默认配置，不表示关闭。当前文件解析默认开启；模型能原生处理的 PDF 和图片，在符合模型限制时直接传递。否则，文字 PDF 和 Office 文档在本地提取文字，扫描页使用 OCR，图片使用 OCR 和视觉描述。提取出的文字占用主模型的上下文窗口。

关闭转换使用：

{
  "plugins": [
    { "id": "file-parser", "enabled": false }
  ]
}

关闭后，原生支持的输入仍可使用；模型不支持的输入会被拒绝。配置会检查插件 ID、字段和取值，未知配置不会被静默忽略。

PDF 处理方式

`pdf.engine`	行为
`auto`（默认模式）	优先原生处理；需要转换时提取文字，并对扫描页或文字不足的页使用 OCR。
`native`	只允许原生 PDF 输入。模型不支持或超过原生限制时拒绝，不自动转为文字。
`ocr`	强制走文字转换，即使模型支持原生 PDF；有可用文字的页仍本地提取，需要识别的页才调用 OCR。

请求中省略 pdf.engine 会继承默认配置；没有租户或平台覆盖时即为自动模式。当前请求参数只接受显式的 native 或 ocr，不能用字符串 "auto" 覆盖已有默认。可在控制台将租户 PDF 默认方式设为自动。

{
  "plugins": [
    { "id": "file-parser", "pdf": { "engine": "ocr" } }
  ]
}

pdf.engine 只影响 PDF。可用 "image": { "describe": false } 关闭非原生图片转换；它不关闭原生视觉输入，也不影响文档。

配置优先级

从高到低：平台策略 > 租户锁定 > 本次请求 > 租户默认 > 插件默认。

平台策略决定的值不可被覆盖。租户锁定后，请求尝试改变锁定值会返回 PLUGIN_SETTING_LOCKED。没有锁定的字段可以在本次请求中覆盖，且不会修改租户默认配置。文件大小、页数等平台限制不可通过请求调整。

费用

本地文字提取不产生额外模型用量；转换后的文字仍按主模型输入计费。
OCR 按实际处理页数计量，图片描述按描述模型的输入、缓存输入和输出用量计量；单价以所用模型的价格为准。
OCR、图片描述和主模型是各自的用量记录。主模型失败不会抹掉已经发生的转换用量。
命中解析缓存不发起新的转换子调用，因此不新增这部分用量；下一轮主模型仍按实际输入和输出计费。

解析注明与下一轮带回

转换成功的响应会携带文件注明（annotations）。保留完整对象，不要修改哈希或解析内容：

{
  "type": "file",
  "file": {
    "hash": "<原样保留服务返回的哈希>",
    "name": "notes.pdf",
    "content": [{ "type": "text", "text": "解析出的文字" }]
  }
}

入口	非流式位置	流式位置
Chat Completions	`choices[].message.annotations`	`choices[].delta.annotations`，每个 choice 返回一次
Anthropic Messages	响应消息顶层 `annotations`	`message_start.message.annotations`
Responses	`output[]` 中 message 的 `content[]` 内 `output_text.annotations`	`response.content_part.done`、`response.output_item.done` 和响应终态中的对应文字快照

已有的引用注明及其下标会保留；Responses 的未完成快照不插入文件注明，完成快照才附加。Messages 的顶层字段和 Responses 中的 type: "file" 是平台扩展；不要把文件注明变成 Anthropic content block。只有实际转换才产生这些注明，原生直传不产生。Responses 若只返回工具调用、拒绝块或空输出，不会为携带注明而合成文字消息。

下一轮保留原始用户输入和上一轮 assistant 内容，把注明一同带回：

// Chat Completions
messages.push(response.choices[0].message);

// Anthropic Messages：保留顶层扩展字段
messages.push({
  role: "assistant",
  content: response.content,
  annotations: response.annotations,
});

// Responses：保留 output_text 的 annotations
input.push(...response.output);

然后追加新的用户问题。流式客户端同样保留聚合结果中的注明；若自行组装消息，需从上述事件位置收集它们。SDK 类型未声明扩展字段时，使用其额外字段机制或读取原始 JSON。

带回内容与服务端解析结果、原文件、配置及模型能力匹配时，会跳过重新解析。修改内容、切换配置或缓存不可用时，不保证复用；客户端注明不能自行证明“已解析”。即使不再携带原文件，注明中的文字也会作为普通对话上下文送给模型。单独传 previous_response_id 不等于显式带回文件注明。

查看模型支持方式

GET /model/v1/models 的 architecture.input_modalities 使用 OpenRouter 形状，只列原生模态。原生 PDF 能力表示为 file，不会因启用插件而加入这一数组。

扩展字段 x_praxis.input_modalities 按输入类型标注 native、converted 或 unsupported：

{
  "architecture": { "input_modalities": ["text"] },
  "x_praxis": {
    "input_modalities": {
      "text": "native",
      "image": "converted",
      "pdf": "converted",
      "docx": "converted",
      "pptx": "converted",
      "xlsx": "converted",
      "audio": "unsupported",
      "video": "unsupported"
    }
  }
}

这是一个仅支持原生文字的对话模型的示例。标注由模型能力和已注册插件推导；converted 表示存在转换路径，实际请求还受租户设置、请求配置和限额约束。嵌入、OCR 等非对话调用不因此获得对话插件。音频、视频目前没有转换插件，只有模型原生支持时才可输入。

限制

需要转换的文件必须提供内联内容，或使用当前入口支持的已授权文件引用；插件不下载任意外部 URL。
当前支持 PDF、DOCX、PPTX、XLSX 和图片转换。Office 提取正文、幻灯片文字及单元格值，不解析嵌入对象或其中的图片。
单文件最多 10 MiB，每请求累计最多 20 MiB；PDF 解析最多 100 页，付费 OCR 最多 20 页，每批最多 10 页；每请求最多 4 个付费子调用、同时最多 2 个。
转换总时限为 90 秒；OCR 子调用最多 45 秒，图片描述最多 30 秒。流式转换期间可能先收到 : PRAXIS PROCESSING 保活注释，它不是模型输出。
提取文字最多 1,000,000 字符，表格每 sheet 最多 1,000 行。模型自身的上下文和输入限制仍然适用。
Responses 仅在创建时转换新提交的输入；retrieve、cancel 等操作不重新转换。需要转换的 background: true 请求返回 PLUGIN_BACKGROUND_UNSUPPORTED。
并发请求同时未命中缓存时，可能各自发起付费转换。主模型失败时，当前接口不保证返回已解析的文件注明。

插件

配置与默认行为

PDF 处理方式

配置优先级

费用

解析注明与下一轮带回

查看模型支持方式

限制

本页内容