文档与文件工具

OmniDoc 提供同步文件工具和可追踪的异步文档操作。先调用能力端点，不要在客户端写死支持范围或限额。

能力发现

GET /api/v1/document-operations/capabilities
GET /api/v1/artifacts/convert/capabilities

返回当前开放的操作、输入格式、计费方式和技术上限。unavailable 中的能力不能创建。

异步文档操作

POST /api/v1/document-operations
Idempotency-Key: unique-request-id

{
  "document_id": "4q8mx2q9z1k7p6ra",
  "kind": "visual_extract"
}

本接口必须携带 Idempotency-Key。kind 当前包括：

• extract：结构化提取，免费。
• pdf_to_html：PDF 转在线 HTML，免费。
• visual_extract：视觉结构化提取，按页计费（每页 1 积分）。开始前按余额确定可处理的页数（最多 20 页），余额不足 1 页时返回 402；完成后按实际处理的页数扣费，余额可能变为负数。

查询与取消：

GET  /api/v1/document-operations/{operation_id}
GET  /api/v1/document-operations?limit=25
POST /api/v1/document-operations/{operation_id}/cancel

完成后响应中的 output_document_id 可继续进入文件库或其他任务，credit_operation_id 可查询结算凭证。

PDF 工具

POST /api/v1/file-tools/pdf/merge
POST /api/v1/file-tools/pdf/split
POST /api/v1/file-tools/pdf/compress

合并示例：

{"document_ids":["4q8mx2q9z1k7p6ra","b6t1n8c3v9m2x5ka"]}

拆分示例：

{"document_id":"4q8mx2q9z1k7p6ra","ranges":["1-3","5","8-10"]}

图片工具

POST /api/v1/file-tools/image/convert
POST /api/v1/file-tools/image/compress

{
  "document_id": "4q8mx2q9z1k7p6ra",
  "target_format": "webp",
  "quality": 85
}

工具只接受当前账号拥有且类型匹配的文档。对二进制响应使用流式下载，并依据响应头保存文件名和类型。