文档理解
Gemini 模型可以处理 PDF 格式的文档,使用原生视觉来理解整个文档上下文。这不仅仅是文本提取,允许 Gemini :
分析和解释内容,包括文本、图像、图表、图表和表格,甚至是长达 1000 页的长文档。
将信息提取到 结构化输出 格式。
根据文档中的视觉和文本元素总结并回答问题。
转录文档内容(例如,转换为 HTML),保留布局和格式,以供下游应用程序使用。
您还可以传递 Microsoft Office 和 OpenDocument 文件,例如 Word 文档、PowerPoint 演示文稿和 Excel 电子表格。详细信息请参见 Office 和 OpenDocument 文件。其他非 PDF 文档(例如 TXT、Markdown 或 HTML 文件)将作为纯文本进行处理,从而消除了图表或格式等上下文。
内联传递 PDF 数据 #
您可以在请求中内联传递 PDF 数据。这最适合较小的文档或临时处理,您不需要在后续请求中引用该文件。我们建议使用 Files API 用于在多轮交互中需要参考的较大文档,以改善请求延迟并减少带宽使用。
以下示例向您展示如何内联传递 PDF 数据:
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)
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();
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(""));
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)
}
}
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"}
]
}'
gemini-api analyze -i path/to/document.pdf "Summarize this document"
您还可以上传本地PDF文件进行处理:
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)
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();
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(""));
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)
}
}
FILE=$(gemini-api files upload file.pdf --wait)
gemini-api analyze -i "$FILE" "Summarize this document"
使用 Files API 上传 PDF #
我们建议您将 Files API 用于较大的文件或当您打算跨多个请求重复使用文档时。通过将文件上传与模型请求解耦,可以改善请求延迟并减少带宽使用。
来自 URL 的大型 PDF #
使用文件 API 简化从 URL 上传和处理大型 PDF 文件的过程:
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)
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();
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(""));
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)
}
}
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
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"
本地存储的大型 PDF #
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)
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();
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(""));
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)
}
}
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
FILE=$(gemini-api files upload large_file.pdf --wait)
gemini-api analyze -i "$FILE" "Summarize this document"
您可以通过调用验证API是否成功存储了上传的文件并获取其元数据 files.get。只有 name (并且通过扩展, uri)是独一无二的。
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))
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());
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)
}
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
FILE=$(gemini-api files upload example.pdf)
gemini-api files get "$FILE" -o json
传递多个 PDF #
Gemini API 能够在单个请求中处理多个 PDF 文档(最多 1000 页),只要文档和文本提示的组合大小保持在模型的上下文窗口范围内。
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)
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();
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(""));
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)
}
}
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"
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."
Office 和 OpenDocument 文件 #
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,因此模型会接收单元格值,但不会接收公式或格式。
- 消耗臭氧层物质文件:仅 第一张 已读。该模型接收其单元数据和公式。
工作簿中的其他工作表将被忽略。要分析不同的工作表,请将其移至第一个位置或将其另存为单独的文件。
无论您在请求中传递文件还是在工具中返回文件,文件的处理方式都是相同的 功能反应。现有文件大小和页数限制适用于整个文件。
以下示例使用 Files API 上传 PowerPoint 演示文稿,并要求模型对其进行总结:
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)
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();
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."}
]
}'
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."
工具还可以将这些文件返回到模型。详细信息请参见 多模态功能响应.
技术细节 #
Gemini 支持最大 50MB 的 PDF 文件或 1000 页。此限制适用于内联数据和 Files API 上传。每个文档页相当于258 token。
虽然除了模型的像素数之外,文档中的像素数没有具体限制 上下文窗口,较大的页面会缩小到 3072 x 3072 的最大分辨率,同时保留其原始纵横比,而较小的页面会放大到 768 x 768 像素。除了带宽之外,较小尺寸的页面不会降低成本,也不会提高较高分辨率的页面的性能。
Gemini 3型号 #
Gemini 3 引入了对多模态视觉处理的精细控制 media_resolution 参数。您现在可以将每个媒体部分的分辨率设置为低、中或高。通过此添加,PDF 文档的处理已更新:
原生文本包含: 提取 PDF 中本机嵌入的文本并将其提供给模型。
计费和 token 报告:
你是 未收费 对于 token 源自提取的 原生文本 在 PDF 中。
在
usage_metadataAPI 响应的部分中,处理 PDF 页面(作为图像)生成的 token 现在计入IMAGE形式,而不是单独的DOCUMENT与某些早期版本一样的模式。
有关媒体分辨率参数的更多详细信息,请参阅 媒体分辨率 指导。
文件类型 #
文档视觉有意义地理解 PDF 以及 DOC、PPT 和 ODP 文件,这些文件呈现为页面图像。 DOCX、DOTX、ODT 和 PPTX 文件将转换为文本,电子表格将作为表格数据读取。详细信息请参见 Office 和 OpenDocument 文件.
从技术上讲,您可以传递其他 MIME 类型来理解文档,例如 TXT、Markdown、HTML、XML 等。但是,这些类型被提取为纯文本,这意味着模型无法理解渲染文件中存在的视觉元素。任何文件类型细节(例如图表、图表、HTML 标签、Markdown 格式等)都将丢失。
要了解其他文件输入方法,请参阅 文件输入方式 指导。
最佳实践 #
为了获得最佳结果:
- 上传前将页面旋转到正确的方向。
- 避免页面模糊。
- 如果使用单个页面,请将文本提示放在页面后面。
后续步骤 #
要了解更多信息,请参阅以下资源: