文档理解

Gemini OpenAI 兼容文档理解适合已经使用 OpenAI chat/completions 的客户，在同一个 messages[].content 数组中传入文本指令和文件内容。当前推荐写法是 type: "file" 搭配 file.file_data 的 data URL，适合 PDF、TXT、DOCX 等小到中等大小文件的联调和结构化抽取。

在 OpenAI 兼容格式里，不要只把 PDF URL 当普通文本发给模型，否则模型可能只能看到 URL 字符串。大文件或远程文件可以评估 Gemini 原生 fileData.fileUri，但前提是 URL 必须是上游可直接读取、响应 MIME 正确的文件直链；不确定时请使用本页的 file_data data URL。

接口地址

POST https://{your-domain}/v1/chat/completions

OpenAI SDK 的 base_url：

https://{your-domain}/v1

示例模型：

gemini-3.5-flash

鉴权

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求结构

字段	类型	必填	说明
`model`	string	是	支持文档理解的 Gemini 模型名称。
`messages[].content`	array	是	多模态内容数组，包含 `text` 和 `file`。
`content[].type`	string	是	文本传 `text`，文件传 `file`。
`content[].text`	string	文本必填	文档处理指令，例如摘要、抽取、问答、分类。
`content[].file.filename`	string	文件必填	文件名，建议带真实扩展名。
`content[].file.file_data`	string	文件必填	data URL，例如 `data:application/pdf;base64,...`。
`max_tokens`	integer	否	最大输出 token 数。
`temperature`	number	否	抽取任务建议低温度。
`response_format`	object	否	需要强结构化 JSON 时可传。

常见 data URL 前缀：

文件类型	data URL 前缀
PDF	`data:application/pdf;base64,`
TXT	`data:text/plain;base64,`
Markdown	`data:text/markdown;base64,`
DOCX	`data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,`

非流式文档理解

curl

curl --request POST \
  --url 'https://{your-domain}/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-3.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "请阅读这份 PDF，用中文输出：1. 核心摘要；2. 三条要点；3. 需要人工复核的字段。"
          },
          {
            "type": "file",
            "file": {
              "filename": "sample.pdf",
              "file_data": "data:application/pdf;base64,JVBERi0xLjcKJcTl8uXrp..."
            }
          }
        ]
      }
    ],
    "max_tokens": 1024,
    "temperature": 0.2,
    "stream": false
  }'

请求体

{
  "model": "gemini-3.5-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "请阅读这份 PDF，用中文输出：1. 核心摘要；2. 三条要点；3. 需要人工复核的字段。"
        },
        {
          "type": "file",
          "file": {
            "filename": "sample.pdf",
            "file_data": "data:application/pdf;base64,JVBERi0xLjcKJcTl8uXrp..."
          }
        }
      ]
    }
  ],
  "max_tokens": 1024,
  "temperature": 0.2,
  "stream": false
}

响应示例

{
  "id": "chatcmpl-doc-abc123",
  "object": "chat.completion",
  "created": 1784700000,
  "model": "gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1. 核心摘要：这份 PDF 内容较短，主要用于验证文件读取和文档解析流程。\n\n2. 三条要点：\n- 文档结构简单，正文较少。\n- 可作为接口联调样例。\n- 不包含复杂表格、签章或多页长文本。\n\n3. 需要人工复核的字段：如果换成真实业务文件，合同金额、日期、签署方、身份证号、发票号码等字段建议人工复核。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 640,
    "completion_tokens": 158,
    "total_tokens": 798
  }
}

结构化 JSON 抽取

当客户需要固定字段，可以传 response_format。下面示例要求模型只返回 JSON。

{
  "model": "gemini-3.5-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是文档信息抽取助手。只返回 JSON，不要返回 Markdown。字段缺失时使用 null。"
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "从文件中提取 title、date、parties、amount、summary。"
        },
        {
          "type": "file",
          "file": {
            "filename": "contract.pdf",
            "file_data": "data:application/pdf;base64,JVBERi0xLjcKJcTl8uXrp..."
          }
        }
      ]
    }
  ],
  "response_format": {
    "type": "json_object"
  },
  "max_tokens": 1200,
  "temperature": 0.1
}

响应示例：

{
  "id": "chatcmpl-doc-json-abc123",
  "object": "chat.completion",
  "created": 1784700000,
  "model": "gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"title\":\"样例合同\",\"date\":\"2026-07-22\",\"parties\":[\"甲方示例公司\",\"乙方示例公司\"],\"amount\":null,\"summary\":\"文档用于演示合同字段抽取。\"}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 780,
    "completion_tokens": 72,
    "total_tokens": 852
  }
}

流式文档理解

文档理解也可以尝试 stream: true。如果渠道不支持文件流式，建议改用非流式或 Gemini 原生流式。

curl -N --request POST \
  --url 'https://{your-domain}/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-3.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "请流式总结这份 PDF，先输出摘要，再输出要点列表。"
          },
          {
            "type": "file",
            "file": {
              "filename": "sample.pdf",
              "file_data": "data:application/pdf;base64,JVBERi0xLjcKJcTl8uXrp..."
            }
          }
        ]
      }
    ],
    "max_tokens": 1024,
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

响应为 SSE：

data: {"id":"chatcmpl-doc-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-doc-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{"content":"摘要：这份文档内容较短，主要用于验证文件读取流程。"},"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-doc-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{"content":"\n要点：\n- 文档结构简单。\n- 可用于接口联调。\n- 真实业务仍需人工复核关键字段。"},"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-doc-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":640,"completion_tokens":76,"total_tokens":716}}

data: [DONE]

Python SDK 示例

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://{your-domain}/v1",
)

pdf_bytes = Path("sample.pdf").read_bytes()
file_data = "data:application/pdf;base64," + base64.b64encode(pdf_bytes).decode("utf-8")

completion = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请总结这份 PDF，并列出三条要点。"},
                {
                    "type": "file",
                    "file": {
                        "filename": "sample.pdf",
                        "file_data": file_data,
                    },
                },
            ],
        }
    ],
    max_tokens=1024,
    temperature=0.2,
)

print(completion.choices[0].message.content)

JavaScript SDK 示例

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://{your-domain}/v1",
});

const pdfBase64 = fs.readFileSync("sample.pdf").toString("base64");

const completion = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "请总结这份 PDF，并列出三条要点。" },
        {
          type: "file",
          file: {
            filename: "sample.pdf",
            file_data: `data:application/pdf;base64,${pdfBase64}`,
          },
        },
      ],
    },
  ],
  max_tokens: 1024,
  temperature: 0.2,
});

console.log(completion.choices[0].message.content);

选择 OpenAI 兼容还是 Gemini 原生

场景	建议
客户已有 OpenAI SDK 封装	使用 OpenAI 兼容格式。
小文件、低频联调、快速迁移	使用 `type: "file"` + `file_data`。
大文件、远程文件 URL、长文档	若能提供上游可读且 `Content-Type` 正确的稳定直链，可评估 Gemini 原生 `fileData.fileUri`；否则拆分文件或继续使用 data URL。
需要视频理解	使用 Gemini 原生视频理解，不建议 OpenAI 兼容视频写法。
需要完全贴近 Gemini 官方参数	使用 Gemini 原生格式。

常见问题

场景	表现	处理方式
直接传 PDF URL	模型只复述 URL 或说无法访问	改用 `type: "file"` + `file_data`；若使用 Gemini 原生 URL 方式，必须先确认 URL 是文件直链。
请求体过大	413、超时或上游拒绝	拆分文档，或转存为上游可读且响应 MIME 正确的稳定文件直链后再使用原生格式。
文件无法解析	MIME 与文件内容不一致	使用真实 MIME 类型，并保留正确文件扩展名。
抽取 JSON 不稳定	返回 Markdown 或自然语言	使用 system 指令、`response_format`，并在业务侧做 JSON 校验。
关键字段不可信	模型可能误读扫描件或表格	对金额、日期、身份信息、合同主体等字段保留人工复核。

开始使用

API 参考

模型与计费

指南

参考

接口地址

鉴权

请求结构

非流式文档理解

curl

请求体

响应示例

结构化 JSON 抽取

流式文档理解

Python SDK 示例

JavaScript SDK 示例

选择 OpenAI 兼容还是 Gemini 原生

常见问题

​接口地址

​鉴权

​请求结构

​非流式文档理解

​curl

​请求体

​响应示例

​结构化 JSON 抽取

​流式文档理解

​Python SDK 示例

​JavaScript SDK 示例

​选择 OpenAI 兼容还是 Gemini 原生

​常见问题

接口地址

鉴权

请求结构

非流式文档理解

curl

请求体

响应示例

结构化 JSON 抽取

流式文档理解

Python SDK 示例

JavaScript SDK 示例

选择 OpenAI 兼容还是 Gemini 原生

常见问题