# 文档理解

Gemini 模型可以处理 PDF 格式的文档，使用原生视觉来理解整个文档上下文。这不仅仅是文本提取，允许 Gemini ：

* 分析和解释内容，包括文本、图像、图表、图表和表格，甚至是长达 1000 页的长文档。

* 将信息提取到 [结构化输出](/docs/structured-output) 格式。

* 根据文档中的视觉和文本元素总结并回答问题。

* 转录文档内容（例如，转换为 HTML），保留布局和格式，以供下游应用程序使用。

您还可以传递 Microsoft Office 和 OpenDocument 文件，例如 Word 文档、PowerPoint 演示文稿和 Excel 电子表格。详细信息请参见 [Office 和 OpenDocument 文件](/docs/document-processing#office-documents)。其他非 PDF 文档（例如 TXT、Markdown 或 HTML 文件）将作为纯文本进行处理，从而消除了图表或格式等上下文。

## 内联传递 PDF 数据  {% #inline_data %}

您可以在请求中内联传递 PDF 数据。这最适合较小的文档或临时处理，您不需要在后续请求中引用该文件。我们建议使用 [Files API](/docs/document-processing#large-pdfs)
用于在多轮交互中需要参考的较大文档，以改善请求延迟并减少带宽使用。

以下示例向您展示如何内联传递 PDF 数据：

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import base64

client = genai.Client()

with open('path/to/document.pdf', 'rb') as f:
    pdf_bytes = f.read()

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {
            "type": "document",
            "data": base64.b64encode(pdf_bytes).decode('utf-8'),
            "mime_type": "application/pdf"
        },
        {"type": "text", "text": "Summarize this document"}
    ]
)

print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

async function main() {
    const pdfData = fs.readFileSync("path/to/document.pdf", {
        encoding: "base64"
    });

    const interaction = await ai.interactions.create({
        model: "gemini-4-hydrogen",
        input: [
            { type: "text", text: "Summarize this document" },
            {
                type: "document",
                data: pdfData,
                mime_type: "application/pdf"
            }
        ]
    });
    console.log(interaction.output_text);
}

await main();
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

Client client = new Client();

byte[] pdfBytes = Files.readAllBytes(Paths.get("path/to/document.pdf"));
String base64Pdf = Base64.getEncoder().encodeToString(pdfBytes);

Content docContent =
    DocumentContent.builder()
        .data(base64Pdf)
        .mimeType(DocumentContentMimeType.APPLICATION_PDF)
        .build();
Content textContent = TextContent.builder().text("Summarize this document").build();

List<Content> contents = Arrays.asList(docContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-4-hydrogen"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    pdfBytes, err := os.ReadFile("path/to/document.pdf")
    if err != nil {
        log.Fatal(err)
    }
    base64Pdf := base64.StdEncoding.EncodeToString(pdfBytes)

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-4-hydrogen"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    Data:     genai.Ptr(base64Pdf),
                    MimeType: interactions.DocumentContentMimeTypeApplicationPdf.ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: "Summarize this document",
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
PDF_PATH="path/to/document.pdf"

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
  "model": "gemini-4-hydrogen",
  "input": [
    {
      "type": "document",
      "data": "'$(base64 $B64FLAGS $PDF_PATH)'",
      "mime_type": "application/pdf"
    },
    {"type": "text", "text": "Summarize this document"}
  ]
}'
```
{% /tab %}

{% tab label="CLI" %}
```bash
gemini-api analyze -i path/to/document.pdf "Summarize this document"
```
{% /tab %}
{% /tabs %}

您还可以上传本地PDF文件进行处理：

{% tabs %}
{% tab label="Python" %}
```python
from google import genai

client = genai.Client()

uploaded_file = client.files.upload(file="file.pdf")

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "document", "uri": uploaded_file.uri, "mime_type": uploaded_file.mime_type},
        {"type": "text", "text": "Summarize this document"}
    ]
)
print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
    const uploadedFile = await ai.files.upload({
        file: "file.pdf",
        config: { mimeType: "application/pdf" }
    });

    const interaction = await ai.interactions.create({
        model: "gemini-4-hydrogen",
        input: [
            { type: "text", text: "Summarize this document" },
            {
                type: "document",
                uri: uploadedFile.uri,
                mime_type: uploadedFile.mimeType
            }
        ]
    });
    console.log(interaction.output_text);
}

await main();
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File uploadedFile =
    client.files.upload(
        new java.io.File("file.pdf"),
        UploadFileConfig.builder().mimeType("application/pdf").build());

Content docContent =
    DocumentContent.builder()
        .uri(uploadedFile.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(uploadedFile.mimeType().orElse("application/pdf")))
        .build();
Content textContent = TextContent.builder().text("Summarize this document").build();

List<Content> contents = Arrays.asList(docContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-4-hydrogen"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "file.pdf", &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-4-hydrogen"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(uploadedFile.URI),
                    MimeType: interactions.DocumentContentMimeType(uploadedFile.MIMEType).ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: "Summarize this document",
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="CLI" %}
```bash
FILE=$(gemini-api files upload file.pdf --wait)
gemini-api analyze -i "$FILE" "Summarize this document"
```
{% /tab %}
{% /tabs %}

## 使用 Files API 上传 PDF  {% #large-pdfs %}

我们建议您将 Files API 用于较大的文件或当您打算跨多个请求重复使用文档时。通过将文件上传与模型请求解耦，可以改善请求延迟并减少带宽使用。

{% callout type="note" %}
Files API 在提供 Gemini API 的所有地区免费提供。上传的文件将存储 48 小时。
{% /callout %}

### 来自 URL 的大型 PDF  {% #large-pdfs-urls %}

使用文件 API 简化从 URL 上传和处理大型 PDF 文件的过程：

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://arxiv.org/pdf/2312.11805"

doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

sample_doc = client.files.upload(
  file=doc_io,
  config=dict(
    mime_type='application/pdf')
)

prompt = "Summarize this document"

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "document", "uri": sample_doc.uri, "mime_type": sample_doc.mime_type},
        {"type": "text", "text": prompt}
    ]
)
print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {

    const pdfBuffer = await fetch("https://arxiv.org/pdf/2312.11805")
        .then((response) => response.arrayBuffer());

    const fileBlob = new Blob([pdfBuffer], { type: 'application/pdf' });

    const file = await ai.files.upload({
        file: fileBlob,
        config: {
            displayName: 'A17_FlightPlan.pdf',
        },
    });

    let getFile = await ai.files.get({ name: file.name || "" });
    while (getFile.state === 'PROCESSING') {
        getFile = await ai.files.get({ name: file.name || "" });
        console.log(`current file status: ${getFile.state}`);
        console.log('File is still processing, retrying in 5 seconds');

        await new Promise((resolve) => {
            setTimeout(resolve, 5000);
        });
    }
    if (file.state === 'FAILED') {
        throw new Error('File processing failed.');
    }

    const interaction = await ai.interactions.create({
        model: 'gemini-4-hydrogen',
        input: [
            { type: "document", uri: file.uri, mime_type: file.mimeType },
            { type: "text", text: "Summarize this document" }
        ],
    });

    console.log(interaction.output_text);

}

await main();
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

String longContextPdfPath = "https://arxiv.org/pdf/2312.11805";
HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder().uri(URI.create(longContextPdfPath)).build();
byte[] pdfBytes = httpClient.send(request, HttpResponse.BodyHandlers.ofByteArray()).body();

File sampleDoc =
    client.files.upload(
        pdfBytes, UploadFileConfig.builder().mimeType("application/pdf").build());

String prompt = "Summarize this document";

Content docContent =
    DocumentContent.builder()
        .uri(sampleDoc.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(sampleDoc.mimeType().orElse("application/pdf")))
        .build();
Content textContent = TextContent.builder().text(prompt).build();

List<Content> contents = Arrays.asList(docContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-4-hydrogen"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "bytes"
    "context"
    "fmt"
    "io"
    "log"
    "net/http"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    longContextPdfPath := "https://arxiv.org/pdf/2312.11805"
    resp, err := http.Get(longContextPdfPath)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    pdfBytes, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }

    sampleDoc, err := client.Files.Upload(ctx, bytes.NewReader(pdfBytes), &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    prompt := "Summarize this document"

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-4-hydrogen"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(sampleDoc.URI),
                    MimeType: interactions.DocumentContentMimeType(sampleDoc.MIMEType).ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
PDF_PATH="https://arxiv.org/pdf/2312.11805"
DISPLAY_NAME="Gemini_paper"
PROMPT="Summarize this document"

wget -O "${DISPLAY_NAME}.pdf" "${PDF_PATH}"

MIME_TYPE=$(file -b --mime-type "${DISPLAY_NAME}.pdf")
NUM_BYTES=$(wc -c < "${DISPLAY_NAME}.pdf")

echo "MIME_TYPE: ${MIME_TYPE}"
echo "NUM_BYTES: ${NUM_BYTES}"

tmp_header_file=upload-header.tmp

curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GEMINI_API_KEY}" \
-D upload-header.tmp \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${DISPLAY_NAME}.pdf" 2> /dev/null > file_info.json

file_uri=$(jq -r ".file.uri" file_info.json)
echo "file_uri: ${file_uri}"

cat << EOF > payload.json
{
"model": "gemini-4-hydrogen",
"input": [
  {"type": "text", "text": "${PROMPT}"},
  {"type": "document", "uri": "${file_uri}", "mime_type": "application/pdf"}
]
}
EOF

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -X POST \
  -d @payload.json 2> /dev/null > response.json

cat response.json
echo

jq ".steps[-1].content[0].text" response.json

rm "${DISPLAY_NAME}.pdf"
rm payload.json
```
{% /tab %}

{% tab label="CLI" %}
```bash
curl -sL -o Gemini_paper.pdf "https://arxiv.org/pdf/2312.11805"
FILE=$(gemini-api files upload Gemini_paper.pdf --wait)
gemini-api analyze -i "$FILE" "Summarize this document"
```
{% /tab %}
{% /tabs %}

### 本地存储的大型 PDF  {% #large-pdfs-local %}

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import pathlib

client = genai.Client()

file_path = pathlib.Path('large_file.pdf')
sample_file = client.files.upload(
    file=file_path,
)

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "document", "uri": sample_file.uri, "mime_type": sample_file.mime_type},
        {"type": "text", "text": "Summarize this document"}
    ]
)
print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
    const file = await ai.files.upload({
        file: 'path-to-localfile.pdf',
        config: {
            displayName: 'A17_FlightPlan.pdf',
        },
    });

    let getFile = await ai.files.get({ name: file.name || "" });
    while (getFile.state === 'PROCESSING') {
        getFile = await ai.files.get({ name: file.name || "" });
        console.log(`current file status: ${getFile.state}`);
        console.log('File is still processing, retrying in 5 seconds');

        await new Promise((resolve) => {
            setTimeout(resolve, 5000);
        });
    }
    if (file.state === 'FAILED') {
        throw new Error('File processing failed.');
    }

    const interaction = await ai.interactions.create({
        model: 'gemini-4-hydrogen',
        input: [
            { type: "document", uri: file.uri, mime_type: file.mimeType },
            { type: "text", text: "Summarize this document" }
        ],
    });

    console.log(interaction.output_text);

}

await main();
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File sampleFile =
    client.files.upload(
        new java.io.File("large_file.pdf"),
        UploadFileConfig.builder().mimeType("application/pdf").build());

Content docContent =
    DocumentContent.builder()
        .uri(sampleFile.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(sampleFile.mimeType().orElse("application/pdf")))
        .build();
Content textContent = TextContent.builder().text("Summarize this document").build();

List<Content> contents = Arrays.asList(docContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-4-hydrogen"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    sampleFile, err := client.Files.UploadFromPath(ctx, "large_file.pdf", &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-4-hydrogen"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(sampleFile.URI),
                    MimeType: interactions.DocumentContentMimeType(sampleFile.MIMEType).ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: "Summarize this document",
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
PDF_PATH="path/to/large_file.pdf"
NUM_BYTES=$(wc -c < "${PDF_PATH}")
DISPLAY_NAME=TEXT
tmp_header_file=upload-header.tmp

curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GEMINI_API_KEY}" \
-D upload-header.tmp \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: application/pdf" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${PDF_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -X POST \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": [
      {"type": "document", "uri": '$file_uri', "mime_type": "application/pdf"},
      {"type": "text", "text": "Can you add a few more lines to this poem?"}
    ]
  }' 2> /dev/null > response.json

cat response.json
echo

jq ".steps[-1].content[0].text" response.json
```
{% /tab %}

{% tab label="CLI" %}
```bash
FILE=$(gemini-api files upload large_file.pdf --wait)
gemini-api analyze -i "$FILE" "Summarize this document"
```
{% /tab %}
{% /tabs %}

您可以通过调用验证API是否成功存储了上传的文件并获取其元数据 [`files.get`](/api-reference/files/get-file)。只有 `name`
（并且通过扩展， `uri`）是独一无二的。

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import pathlib

client = genai.Client()

fpath = pathlib.Path('example.pdf')
fpath.write_text('hello')

file = client.files.upload(file='example.pdf')

file_info = client.files.get(name=file.name)
print(file_info.model_dump_json(indent=4))
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

Client client = new Client();

Path fpath = Paths.get("example.pdf");
Files.write(fpath, "hello".getBytes(StandardCharsets.UTF_8));

File file =
    client.files.upload(
        fpath.toFile(), UploadFileConfig.builder().mimeType("application/pdf").build());

File fileInfo = client.files.get(file.name().orElse(""), null);
System.out.println(fileInfo.toJson());
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    if err := os.WriteFile("example.pdf", []byte("hello"), 0644); err != nil {
        log.Fatal(err)
    }

    file, err := client.Files.UploadFromPath(ctx, "example.pdf", &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    fileInfo, err := client.Files.Get(ctx, file.Name, nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(fileInfo)
}
```
{% /tab %}

{% tab label="REST" %}
```shell
name=$(jq -r ".file.name" file_info.json)
curl "https://generativelanguage.googleapis.com/v1beta/$name?key=$GEMINI_API_KEY" > file_info.json
name=$(jq -r ".name" file_info.json)
echo name=$name
file_uri=$(jq -r ".uri" file_info.json)
echo file_uri=$file_uri
```
{% /tab %}

{% tab label="CLI" %}
```bash
FILE=$(gemini-api files upload example.pdf)
gemini-api files get "$FILE" -o json
```
{% /tab %}
{% /tabs %}

## 传递多个 PDF  {% #prompt-multiple %}

Gemini API 能够在单个请求中处理多个 PDF 文档（最多 1000 页），只要文档和文本提示的组合大小保持在模型的上下文窗口范围内。

{% tabs %}
{% tab label="Python" %}
```python
from google import genai
import io
import httpx

client = genai.Client()

doc_url_1 = "https://arxiv.org/pdf/2312.11805"
doc_url_2 = "https://arxiv.org/pdf/2403.05530"

doc_data_1 = io.BytesIO(httpx.get(doc_url_1).content)
doc_data_2 = io.BytesIO(httpx.get(doc_url_2).content)

sample_pdf_1 = client.files.upload(
  file=doc_data_1,
  config=dict(mime_type='application/pdf')
)
sample_pdf_2 = client.files.upload(
  file=doc_data_2,
  config=dict(mime_type='application/pdf')
)

prompt = "What is the difference between each of the main benchmarks between these two papers? Output these in a table."

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "document", "uri": sample_pdf_1.uri, "mime_type": sample_pdf_1.mime_type},
        {"type": "document", "uri": sample_pdf_2.uri, "mime_type": sample_pdf_2.mime_type},
        {"type": "text", "text": prompt}
    ]
)

print(interaction.output_text)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function uploadRemotePDF(url = '', displayName = '') {
    const pdfBuffer = await fetch(url)
        .then((response) => response.arrayBuffer());

    const fileBlob = new Blob([pdfBuffer], { type: 'application/pdf' });

    const file = await ai.files.upload({
        file: fileBlob,
        config: {
            displayName: displayName,
        },
    });

    let getFile = await ai.files.get({ name: file.name || "" });
    while (getFile.state === 'PROCESSING') {
        getFile = await ai.files.get({ name: file.name || "" });
        console.log(`current file status: ${getFile.state}`);
        console.log('File is still processing, retrying in 5 seconds');

        await new Promise((resolve) => {
            setTimeout(resolve, 5000);
        });
    }
    if (file.state === 'FAILED') {
        throw new Error('File processing failed.');
    }

    return file;
}

async function main() {
    const file1 = await uploadRemotePDF("https://arxiv.org/pdf/2312.11805", "PDF 1");
    const file2 = await uploadRemotePDF("https://arxiv.org/pdf/2403.05530", "PDF 2");

    const interaction = await ai.interactions.create({
        model: 'gemini-4-hydrogen',
        input: [
            { type: "document", uri: file1.uri, mime_type: file1.mimeType },
            { type: "document", uri: file2.uri, mime_type: file2.mimeType },
            { type: "text", text: "What is the difference between each of the main benchmarks between these two papers? Output these in a table." }
        ],
    });

    console.log(interaction.output_text);
}

await main();
```
{% /tab %}

{% tab label="Java" %}
```java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.DocumentContent;
import com.google.genai.gaos.models.interactions.DocumentContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.UploadFileConfig;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

String docUrl1 = "https://arxiv.org/pdf/2312.11805";
String docUrl2 = "https://arxiv.org/pdf/2403.05530";

HttpClient httpClient = HttpClient.newHttpClient();
byte[] docData1 =
    httpClient
        .send(HttpRequest.newBuilder().uri(URI.create(docUrl1)).build(), HttpResponse.BodyHandlers.ofByteArray())
        .body();
byte[] docData2 =
    httpClient
        .send(HttpRequest.newBuilder().uri(URI.create(docUrl2)).build(), HttpResponse.BodyHandlers.ofByteArray())
        .body();

File samplePdf1 =
    client.files.upload(
        docData1, UploadFileConfig.builder().mimeType("application/pdf").build());
File samplePdf2 =
    client.files.upload(
        docData2, UploadFileConfig.builder().mimeType("application/pdf").build());

String prompt =
    "What is the difference between each of the main benchmarks between these two papers? Output these in a table.";

Content doc1Content =
    DocumentContent.builder()
        .uri(samplePdf1.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(samplePdf1.mimeType().orElse("application/pdf")))
        .build();
Content doc2Content =
    DocumentContent.builder()
        .uri(samplePdf2.uri().orElse(""))
        .mimeType(DocumentContentMimeType.of(samplePdf2.mimeType().orElse("application/pdf")))
        .build();
Content textContent = TextContent.builder().text(prompt).build();

List<Content> contents = Arrays.asList(doc1Content, doc2Content, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-4-hydrogen"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}

{% tab label="Go" %}
```go
package main

import (
    "bytes"
    "context"
    "fmt"
    "io"
    "log"
    "net/http"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    docURL1 := "https://arxiv.org/pdf/2312.11805"
    docURL2 := "https://arxiv.org/pdf/2403.05530"

    resp1, err := http.Get(docURL1)
    if err != nil {
        log.Fatal(err)
    }
    defer resp1.Body.Close()
    docData1, err := io.ReadAll(resp1.Body)
    if err != nil {
        log.Fatal(err)
    }

    resp2, err := http.Get(docURL2)
    if err != nil {
        log.Fatal(err)
    }
    defer resp2.Body.Close()
    docData2, err := io.ReadAll(resp2.Body)
    if err != nil {
        log.Fatal(err)
    }

    samplePdf1, err := client.Files.Upload(ctx, bytes.NewReader(docData1), &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }
    samplePdf2, err := client.Files.Upload(ctx, bytes.NewReader(docData2), &genai.UploadFileConfig{
        MIMEType: "application/pdf",
    })
    if err != nil {
        log.Fatal(err)
    }

    prompt := "What is the difference between each of the main benchmarks between these two papers? Output these in a table."

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-4-hydrogen"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(samplePdf1.URI),
                    MimeType: interactions.DocumentContentMimeType(samplePdf1.MIMEType).ToPointer(),
                }),
                interactions.NewContent(interactions.DocumentContent{
                    URI:      genai.Ptr(samplePdf2.URI),
                    MimeType: interactions.DocumentContentMimeType(samplePdf2.MIMEType).ToPointer(),
                }),
                interactions.NewContent(interactions.TextContent{
                    Text: prompt,
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
DOC_URL_1="https://arxiv.org/pdf/2312.11805"
DOC_URL_2="https://arxiv.org/pdf/2403.05530"
DISPLAY_NAME_1="Gemini_paper"
DISPLAY_NAME_2="Gemini_1.5_paper"
PROMPT="What is the difference between each of the main benchmarks between these two papers? Output these in a table."

upload_pdf() {
local doc_url="$1"
local display_name="$2"

echo "Downloading ${display_name} from ${doc_url}..." >&2
wget -O "${display_name}.pdf" "${doc_url}" 2> /dev/null

local MIME_TYPE=$(file -b --mime-type "${display_name}.pdf")
local NUM_BYTES=$(wc -c < "${display_name}.pdf")

echo "MIME_TYPE: ${MIME_TYPE}" >&2
echo "NUM_BYTES: ${NUM_BYTES}" >&2

local tmp_header_file="upload-header-${display_name}.tmp"

curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D "${tmp_header_file}" \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${display_name}'}}" 2> /dev/null

local upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

echo "Upload URL for ${display_name}: ${upload_url}" >&2

curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${display_name}.pdf" 2> /dev/null > "file_info_${display_name}.json"

local file_uri=$(jq -r ".file.uri" "file_info_${display_name}.json")
echo "file_uri for ${display_name}: ${file_uri}" >&2

rm "${display_name}.pdf"

echo "${file_uri}"
}

file_uri_1=$(upload_pdf "${DOC_URL_1}" "${DISPLAY_NAME_1}")

file_uri_2=$(upload_pdf "${DOC_URL_2}" "${DISPLAY_NAME_2}")

cat << EOF > payload_multi.json
{
"model": "gemini-4-hydrogen",
"input": [
  {"type": "document", "uri": "${file_uri_1}", "mime_type": "application/pdf"},
  {"type": "document", "uri": "${file_uri_2}", "mime_type": "application/pdf"},
  {"type": "text", "text": "${PROMPT}"}
]
}
EOF

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -X POST \
  -d @payload_multi.json 2> /dev/null > response.json

cat response.json
echo

jq ".steps[-1].content[0].text" response.json

rm payload_multi.json
rm "file_info_${DISPLAY_NAME_1}.json"
rm "file_info_${DISPLAY_NAME_2}.json"
```
{% /tab %}

{% tab label="CLI" %}
```bash
curl -sL -o Gemini_paper.pdf "https://arxiv.org/pdf/2312.11805"
curl -sL -o Gemini_1.5_paper.pdf "https://arxiv.org/pdf/2403.05530"
PDF_1=$(gemini-api files upload Gemini_paper.pdf --wait)
PDF_2=$(gemini-api files upload Gemini_1.5_paper.pdf --wait)
gemini-api analyze -i "$PDF_1" -i "$PDF_2" \
  "What is the difference between each of the main benchmarks between these two papers? Output these in a table."
```
{% /tab %}
{% /tabs %}

## Office 和 OpenDocument 文件  {% #office-documents %}

Gemini 型号可以处理 Microsoft Office 和 OpenDocument 文件。使用与 PDF 相同的方式传递它们，无论是内联还是通过 Files API `document`
内容块和以下 MIME 类型之一：

| 文件类型 | 扩展      | MIME类型                                                                      |
| ---- | ------- | --------------------------------------------------------------------------- |
| 文档   | `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document`   |
|      | `.doc`  | `application/msword`                                                        |
|      | `.dotx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.template`   |
|      | `.odt`  | `application/vnd.oasis.opendocument.text`                                   |
| 演讲   | `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
|      | `.ppt`  | `application/vnd.ms-powerpoint`                                             |
|      | `.odp`  | `application/vnd.oasis.opendocument.presentation`                           |
| 电子表格 | `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`         |
|      | `.xls`  | `application/vnd.ms-excel`                                                  |
|      | `.ods`  | `application/vnd.oasis.opendocument.spreadsheet`                            |

这些文件的处理方式如下：

* **DOCX、DOTX、ODT 和 PPTX 文件**：模型接收整个文件的文本，以及 DOCX 和 PPTX 文件的嵌入图像。页面和幻灯片不会呈现为图像，因此可能不会保留页面布局和图表等视觉元素。
* **DOC、PPT 和 ODP 文件**：每个页面或幻灯片都呈现为图像，因此模型可以解释布局、图表和图像。整个文件已处理完毕。
* **XLSX 和 XLS 文件**：仅 **第一张** 已读。其内容会转换为 CSV，因此模型会接收单元格值，但不会接收公式或格式。
* **消耗臭氧层物质文件**：仅 **第一张** 已读。该模型接收其单元数据和公式。

工作簿中的其他工作表将被忽略。要分析不同的工作表，请将其移至第一个位置或将其另存为单独的文件。

无论您在请求中传递文件还是在工具中返回文件，文件的处理方式都是相同的 [功能反应](/docs/function-calling#multimodal)。现有文件大小和页数限制适用于整个文件。

以下示例使用 Files API 上传 PowerPoint 演示文稿，并要求模型对其进行总结：

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```python
from google import genai

client = genai.Client()

deck = client.files.upload(
    file="quarterly_review.pptx",
    config={
        "mime_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
    },
)

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "document", "uri": deck.uri, "mime_type": deck.mime_type},
        {"type": "text", "text": "Summarize the key takeaways from each slide."},
    ],
)

print(interaction.output_text)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
    const deck = await ai.files.upload({
        file: "quarterly_review.pptx",
        config: {
            mimeType: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
        },
    });

    const interaction = await ai.interactions.create({
        model: "gemini-4-hydrogen",
        input: [
            { type: "document", uri: deck.uri, mime_type: deck.mimeType },
            { type: "text", text: "Summarize the key takeaways from each slide." }
        ]
    });
    console.log(interaction.output_text);
}

main();
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```shell
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": [
      {
        "type": "document",
        "uri": "https://generativelanguage.googleapis.com/v1beta/files/FILE_ID",
        "mime_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
      },
      {"type": "text", "text": "Summarize the key takeaways from each slide."}
    ]
  }'
```
{% /tab %}

{% tab filename="sample.sh" label="CLI" %}
```bash
FILE=$(gemini-api files upload quarterly_review.pptx --wait \
  --mime-type application/vnd.openxmlformats-officedocument.presentationml.presentation)
gemini-api analyze -i "$FILE" "Summarize the key takeaways from each slide."
```
{% /tab %}
{% /tabs %}

工具还可以将这些文件返回到模型。详细信息请参见 [多模态功能响应](/docs/function-calling#multimodal).

## 技术细节  {% #technical-details %}

Gemini 支持最大 50MB 的 PDF 文件或 1000 页。此限制适用于内联数据和 Files API 上传。每个文档页相当于258 token。

虽然除了模型的像素数之外，文档中的像素数没有具体限制 [上下文窗口](/docs/long-context)，较大的页面会缩小到 3072 x 3072 的最大分辨率，同时保留其原始纵横比，而较小的页面会放大到 768 x 768 像素。除了带宽之外，较小尺寸的页面不会降低成本，也不会提高较高分辨率的页面的性能。

### Gemini 3型号  {% #gemini-3-models %}

Gemini 3 引入了对多模态视觉处理的精细控制 `media_resolution` 参数。您现在可以将每个媒体部分的分辨率设置为低、中或高。通过此添加，PDF 文档的处理已更新：

1. **原生文本包含：** 提取 PDF 中本机嵌入的文本并将其提供给模型。

1. **计费和 token 报告：**

* 你是 **未收费** 对于 token 源自提取的 **原生文本** 在 PDF 中。

* 在 `usage_metadata` API 响应的部分中，处理 PDF 页面（作为图像）生成的 token 现在计入 `IMAGE`
  形式，而不是单独的 `DOCUMENT` 与某些早期版本一样的模式。

有关媒体分辨率参数的更多详细信息，请参阅 [媒体分辨率](/docs/media-resolution) 指导。

### 文件类型  {% #document-types %}

文档视觉有意义地理解 PDF 以及 DOC、PPT 和 ODP 文件，这些文件呈现为页面图像。 DOCX、DOTX、ODT 和 PPTX 文件将转换为文本，电子表格将作为表​​格数据读取。详细信息请参见 [Office 和 OpenDocument 文件](/docs/document-processing#office-documents).

从技术上讲，您可以传递其他 MIME 类型来理解文档，例如 TXT、Markdown、HTML、XML 等。但是，这些类型被提取为纯文本，这意味着模型无法理解渲染文件中存在的视觉元素。任何文件类型细节（例如图表、图表、HTML 标签、Markdown 格式等）都将丢失。

要了解其他文件输入方法，请参阅 [文件输入方式](/docs/file-input-methods) 指导。

### 最佳实践  {% #best-practices %}

为了获得最佳结果：

* 上传前将页面旋转到正确的方向。
* 避免页面模糊。
* 如果使用单个页面，请将文本提示放在页面后面。

## 后续步骤  {% #whats-next %}

要了解更多信息，请参阅以下资源：

* [文件提示策略](/docs/files#prompt-guide)：Gemini API 支持文字、图片、音频、视频数据提示，也称为多模态提示。

* [系统指令](/docs/text-generation#system-instructions)：系统指令可让您根据您的特定需求和用例来控制模型的行为。
