Gemini 分析媒体

POST /v1beta/models/{model}:generateContent

Gemini 图像、PDF、音频和视频识别请求。

⚠️ 注意：原生 Gemini 格式请求支持通过 inlineData（Base64）或 fileData.fileUri（可公开访问的 URL，支持 YouTube 链接）传递媒体。通过 Gemini File API 上传的文件 URI 能否访问，取决于上游渠道 Key 的权限，建议优先使用可公开访问的 URL。OpenAI 格式（chat/completions）请求转换为 Gemini 时，媒体将统一下载并转换为 inlineData（Base64）传递。

请求参数

路径参数

模型路径参数

参数	类型	默认值	说明	是否必填
`model`	string	—	模型名称，位于 `/v1beta/models/{model}` 路径中。	是

请求头

x-goog-api-key

使用 Gemini API Key 认证。

格式: x-goog-api-key: sk-xxxxxx

请求体

contents[].parts[] 字段

参数	类型	默认值	说明	是否必填
`contents[].role`	string	—	`user` 或 `model`。	否
`contents[].parts[].text`	string	—	对媒体的提问或补充文本。	条件
`contents[].parts[].inlineData.mimeType`	string	—	媒体 MIME 类型，例如 `image/jpeg`、`application/pdf` 或 `audio/mpeg`。	条件
`contents[].parts[].inlineData.data`	string	—	不含 `data:` 前缀的 Base64 数据。	条件
`contents[].parts[].fileData.fileUri`	string	—	公开可访问的媒体 URL，或上游允许访问的 Gemini File API URI。	条件
`contents[].parts[].fileData.mimeType`	string	—	使用 `fileData` 时可提供媒体 MIME 类型。	否

其他请求字段

generationConfig 支持 temperature、topP、topK、maxOutputTokens 和 stopSequences；safetySettings、tools、systemInstruction 的含义与文本聊天相同。

请求体示例

Base64 图片识别

{
  "contents": [{
    "role": "user",
    "parts": [
      { "text": "这张图片中有什么？" },
      { "inlineData": { "mimeType": "image/jpeg", "data": "" } }
    ]
  }],
  "generationConfig": { "maxOutputTokens": 256 }
}

公开 URL 示例

将 inlineData 替换为 fileData：

{
  "contents": [{
    "role": "user",
    "parts": [
      { "text": "总结这份 PDF。" },
      { "fileData": { "mimeType": "application/pdf", "fileUri": "https://example.com/report.pdf" } }
    ]
  }]
}

请求示例代码

以下示例读取本地图片并编码后发送。生产环境请限制文件大小，并校验 MIME 类型。

cURLJavaScriptGoPythonJavaC#

curl -X POST "https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d @request.json

import { readFile } from "node:fs/promises";
const data = (await readFile("photo.jpg")).toString("base64");
const payload = {
  contents: [{
    role: "user",
    parts: [{ text: "描述图片" }, { inlineData: { mimeType: "image/jpeg", data } }]
  }]
};
const response = await fetch("https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent", {
  method: "POST",
  headers: { "x-goog-api-key": process.env.GEMINI_API_KEY },
  body: JSON.stringify(payload)
});
console.log(await response.json());

data, err := os.ReadFile("photo.jpg")
if err != nil { log.Fatal(err) }
payload := fmt.Sprintf(`{"contents":[{"role":"user","parts":[{"text":"描述图片"},{"inlineData":{"mimeType":"image/jpeg","data":"%s"}}]}]}`, base64.StdEncoding.EncodeToString(data))
req, _ := http.NewRequest("POST", "https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent", strings.NewReader(payload))
req.Header.Set("x-goog-api-key", os.Getenv("GEMINI_API_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer res.Body.Close()

import base64
import os
import requests

with open("photo.jpg", "rb") as image:
    data = base64.b64encode(image.read()).decode()
payload = {
    "contents": [{"role": "user", "parts": [{"text": "描述图片"}, {"inlineData": {"mimeType": "image/jpeg", "data": data}}]}],
}
response = requests.post(
    "https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent",
    json=payload,
)
print(response.json())

var bytes = java.nio.file.Files.readAllBytes(java.nio.file.Path.of("photo.jpg"));
var data = java.util.Base64.getEncoder().encodeToString(bytes);
var payload = "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"描述图片\"},{\"inlineData\":{\"mimeType\":\"image/jpeg\",\"data\":\"" + data + "\"}}]}]}";
var request = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent"))
    .header("x-goog-api-key", System.getenv("GEMINI_API_KEY"))
    .POST(java.net.http.HttpRequest.BodyPublishers.ofString(payload))
    .build();
var response = java.net.http.HttpClient.newHttpClient().send(request, java.net.http.HttpResponse.BodyHandlers.ofString());

using System.Net.Http.Json;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-goog-api-key", Environment.GetEnvironmentVariable("GEMINI_API_KEY"));
var data = Convert.ToBase64String(await File.ReadAllBytesAsync("photo.jpg"));
var payload = new {
    contents = new[] {
        new {
            role = "user",
            parts = new object[] { new { text = "描述图片" }, new { inlineData = new { mimeType = "image/jpeg", data } } }
        }
    }
};
var response = await client.PostAsJsonAsync("https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent", payload);
Console.WriteLine(await response.Content.ReadAsStringAsync());

返回响应

响应结构与文本聊天相同，媒体生成或识别结果位于 candidates[].content.parts[]。文本结果读取 text；图像或音频结果读取 inlineData。

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{ "text": "图片中有一只猫。" }]
    },
    "finishReason": "STOP",
    "safetyRatings": []
  }],
  "usageMetadata": { "promptTokenCount": 280, "candidatesTokenCount": 12, "totalTokenCount": 292 }
}

响应字段

字段	类型	说明
`candidates`	array	模型生成的候选结果。
`candidates[].content.parts[].text`	string	媒体识别或问答的文本结果。
`candidates[].content.parts[].inlineData`	object	模型返回的图片或音频数据（如果请求了对应模态）。
`candidates[].finishReason`	string	生成结束原因，例如 `STOP` 或 `SAFETY`。
`candidates[].safetyRatings`	array	安全分类和概率评估。
`usageMetadata`	object	输入、输出及总 token 统计。

OpenAI 格式请求（/v1/chat/completions）转换为 Gemini 时，网关会下载媒体并转换为 inlineData（Base64）后传递；请确保媒体 URL 对网关可访问。

分析媒体