MinerU/docs/next/api/chat.md

Chat 与 Responses

状态: Draft 读者: API 使用者、SDK 开发者、服务端开发者 范围: OpenAI-compatible 文档对话接口 来源: 由根目录旧 Unified API 底稿迁移整理而来

定位

Chat Completions 和 Responses 面向细粒度文档理解场景，例如单张图片 OCR、单个表格提取或一段文本识别。完整 PDF、DOCX、PPTX 等多页文档解析应使用 Tasks。

两套接口都只支持单轮请求，不维护服务端会话历史。

POST /v1/chat/completions

创建 Chat Completion。请求形态兼容 OpenAI Chat Completions 的核心字段。

{
  "model": "mineru-4.0.11",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgo..."
          }
        },
        {
          "type": "text",
          "text": "Text Recognition:"
        }
      ]
    }
  ],
  "stream": false,
  "temperature": 0.7,
  "top_p": 1.0,
  "max_completion_tokens": 4096,
  "n": 1
}

请求字段:

字段	类型	必填	说明
messages	array	是	消息列表。
model	string	是	虚拟模型 ID（mineru-<服务版本>），来自 GET /v1/models，精确匹配当前部署广告值；不用于选择引擎。
tier	string	否	MinerU 扩展字段：解析质量档（flash/basic/standard/advanced），内部复用 Tasks 的 tier 路由与默认选择策略。OpenAI SDK 通过 extra_body 传入。
stream	bool	否	是否流式输出，默认 false。
stream_options.include_usage	bool	否	stream=true 时，最终 chunk 是否包含 usage。
temperature	number	否	采样温度，范围 [0, 2]。
top_p	number	否	核采样，范围 [0, 1]。
max_tokens	integer	否	兼容字段，建议使用 max_completion_tokens。
max_completion_tokens	integer	否	最大输出 token 数。
stop	string 或 array	否	最多 4 个停止序列。
seed	integer	否	尽量确定性采样。
frequency_penalty	number	否	兼容 OpenAI 字段。
presence_penalty	number	否	兼容 OpenAI 字段。
reasoning_effort	string	否	接受但可忽略，保留给未来模型。
n	integer	否	当前仅允许 1。

Message

支持 role:

role	content
system	string 或 text part 数组。
developer	string 或 text part 数组，与 system 等价处理。
user	string 或多模态 part 数组。

不支持 assistant、tool、function role。

user content part:

part	结构	说明
text	{"type":"text","text":"..."}	文本指令。
image_url	{"type":"image_url","image_url":{"url":"..."}}	图片 URL 或 base64 data URI。detail 可传但忽略。

输入限制:

限制项	值
图片或 file 数量	每条消息最多 1 个，二选一。
图片文件大小	小于 10 MiB。
图片分辨率	小于 3500 x 3500。

非流式响应

{
  "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "mineru-4.0.11",
  "system_fingerprint": "fp_44709d6fcb",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "# 文本识别结果\n\n这是从图片中识别出的文字内容..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 86,
    "total_tokens": 206
  }
}

响应字段:

字段	类型	说明
id	string	Completion ID。
object	string	固定为 "chat.completion"。
created	integer	Unix 秒级时间戳。
model	string	实际使用的模型。
system_fingerprint	string	后端配置指纹。
choices[].index	integer	候选索引。
choices[].message.role	string	固定为 "assistant"。
choices[].message.content	string 或 null	输出文本。
choices[].finish_reason	string	stop、length 或 content_filter。
usage	object	token 用量。

流式响应

stream=true 时返回 SSE，每行 data: 后是一个 chat.completion.chunk JSON 对象，最后以 data: [DONE] 结束。

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"mineru-4.0.11","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"mineru-4.0.11","choices":[{"index":0,"delta":{"content":"# 文本"},"finish_reason":null}]}

data: [DONE]

如果 stream_options.include_usage=true，最终 JSON chunk 可以包含 usage，且 choices 为空数组。

不支持的 Chat 参数

以下参数不支持。实现可以返回 400 unsupported_parameter，也可以在明确兼容策略下忽略，但 SDK 不应依赖它们生效:

• tools、tool_choice、function_call、functions、parallel_tool_calls
• audio、modalities
• web_search_options
• prediction
• response_format
• logprobs、top_logprobs
• logit_bias
• service_tier
• store、metadata
• safety_identifier、prompt_cache_key、prompt_cache_retention、user、verbosity

Chat 错误:

HTTP	code	场景
400	invalid_request	消息结构非法、role 不支持、缺少模型等。
400	unsupported_parameter	传入当前不支持的参数。
404	model_not_found	模型不存在。
413	content_too_large	图片或输入超过限制。
429	rate_limit_exceeded	触发 chat 类限流。
503	service_unavailable	模型服务不可用。

POST /v1/responses

创建 Response。该接口与 Chat Completions 功能重叠，但输入输出采用 typed item list。

{
  "model": "mineru-4.0.11",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_image", "image_url": "https://example.com/page.png" },
        { "type": "input_text", "text": "Text Recognition:" }
      ]
    }
  ],
  "stream": false,
  "temperature": 0.7,
  "top_p": 1.0,
  "max_output_tokens": 4096,
  "store": false
}

请求字段:

字段	类型	必填	说明
input	string 或 array	是	字符串或 EasyInputMessage 数组。
instructions	string	否	系统指令，等价于 Chat 的 system message。
model	string	是	模型 ID。
stream	bool	否	是否流式输出。
temperature	number	否	采样温度。
top_p	number	否	核采样。
max_output_tokens	integer	否	最大输出 token 数。
reasoning.effort	string	否	接受但可忽略。
reasoning.summary	string	否	接受但可忽略。
store	bool	否	当前仅允许 false。

EasyInputMessage:

字段	类型	说明
role	string	system、developer 或 user。
content	string 或 array	文本或多模态 part。

Content part:

part	结构	说明
input_text	{"type":"input_text","text":"..."}	文本。
input_image	{"type":"input_image","image_url":"..."}	图片 URL 或 data URI。

不支持 assistant role、tool/function item、reasoning item、conversation 状态 item。

非流式响应

{
  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "model": "mineru-4.0.11",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "该文档主要介绍了...",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 36,
    "output_tokens": 87,
    "total_tokens": 123
  }
}

响应字段:

字段	类型	说明
id	string	Response ID。
object	string	固定为 "response"。
created_at	integer	Unix 秒级时间戳。
status	string	completed、failed 或 incomplete。
model	string	实际使用模型。
output[]	array	输出 item。当前仅返回 message。
output[].content[].type	string	当前仅返回 output_text。
usage	object	token 用量。
incomplete_details	object 或 null	status:"incomplete" 时说明原因。

Responses 流式事件

stream=true 时返回 SSE，使用 event: + data: 双行格式。

事件类型:

事件	含义
response.created	Response 已创建。
response.in_progress	开始处理。
response.output_item.added	新增 message item。
response.content_part.added	新增 output_text part。
response.output_text.delta	文本增量。
response.output_text.done	当前 output_text 完成。
response.content_part.done	当前 part 完成。
response.output_item.done	当前 item 完成。
response.completed	整体完成，携带完整 response 和 usage。

示例:

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_...","output_index":0,"content_index":0,"delta":"# 文本"}

不支持的 Responses 参数

• tools、tool_choice、parallel_tool_calls、max_tool_calls
• background
• conversation、previous_response_id
• include、prompt、top_logprobs、text、truncation、context_management
• metadata、safety_identifier、prompt_cache_key、prompt_cache_retention、user、service_tier

Responses 错误:

HTTP	code	场景
400	invalid_request	input 结构非法、role 不支持、缺少模型等。
400	unsupported_parameter	store=true 或其他不支持参数。
404	model_not_found	模型不存在。
413	content_too_large	输入超过限制。
429	rate_limit_exceeded	触发 chat 类限流。
503	service_unavailable	模型服务不可用。

本地 Server 差异

Local Parse Server 可以暴露同样的 Chat 和 Responses endpoint，但实际可用模型取决于本地 GET /v1/models。

本地实现约束:

• 如果没有可服务的 VLM 或指定模型，应返回 404 model_not_found 或 503 service_unavailable。
• 不得静默切换到 flash。
• 本地部署通常不做 anonymous/registered 的功能售卖差异；启用 API Key 后，通过认证的请求可以使用本地 server 暴露的全部模型能力。
• 如果本地不实现 Chat/Responses，应在 GET /v1/models 中不要暴露对应模型，并对 endpoint 返回明确错误。

这里的 Chat/Responses 为独立协议说明；Python 解析服务不新增这些路由。独立 Uploads 移除后，图片输入使用 URL 或 data URI，不再承诺 purpose=input_image 的 File 输入。