Batch API

Gemini API 支持批处理 API，可让您在一次调用中处理多个请求。如需了解详情，请参阅 Batch API 指南。

方法：models.batchGenerateContent

将一批 models.generateContent 个请求加入队列以进行批处理。

端点

帖子 https://generativelanguage.googleapis.com/v1beta/{batch.model=models/*}:batchGenerateContent

路径参数

batch.model string

必需。用于生成补全的 Model 的名称。

格式：models/{model}。其格式为 models/{model}。

请求正文

请求正文中包含结构如下的数据：

字段
batch.name string

仅限输出。标识符。批次的资源名称。

格式：batches/{batchId}。

batch.displayName string

必需。相应批次的用户定义名称。

batch.inputConfig object (InputConfig)

必需。执行批量处理的实例的输入配置。

batch.output object (GenerateContentBatchOutput)

仅限输出。批量请求的输出。

batch.createTime string (Timestamp format)

仅限输出。批次的创建时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

batch.endTime string (Timestamp format)

仅限输出。批处理完成的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

batch.updateTime string (Timestamp format)

仅限输出。批次上次更新的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

batch.batchStats object (BatchStats)

仅限输出。有关批次的统计信息。

batch.state enum (BatchState)

仅限输出。批次的状态。

batch.priority string (int64 format)

可选。批次的优先级。优先级值较高的批次将先于优先级值较低的批次进行处理。允许使用负值。默认值为 0。

响应正文

如果成功，则响应正文包含一个 Operation 实例。

GenerateContentRequest

请求模型生成补全内容。

字段
model string

必需。用于生成补全的 Model 的名称。

格式：models/{model}。

contents[] object (Content)

必需。与模型当前对话的内容。

对于单轮查询，这是单个实例。对于多轮查询（例如聊天），这是包含对话历史记录和最新请求的重复字段。

tools[] object (Tool)

可选。Model 可能用于生成下一个回答的 Tools 列表。

Tool 是一段代码，可让系统与外部系统进行交互，以在 Model 的知识和范围之外执行操作或一组操作。支持的 Tool 为 Function 和 codeExecution。如需了解详情，请参阅函数调用和代码执行指南。

toolConfig object (ToolConfig)

可选。请求中指定的任何 Tool 的工具配置。如需查看使用示例，请参阅函数调用指南。

safetySettings[] object (SafetySetting)

可选。用于屏蔽不安全内容的唯一 SafetySetting 实例的列表。

此限制将在 GenerateContentRequest.contents 和 GenerateContentResponse.candidates 上强制执行。每种 SafetyCategory 类型不应有多个设置。API 会屏蔽任何不符合这些设置所设阈值的内容和响应。此列表会替换 safetySettings 中指定的每个 SafetyCategory 的默认设置。如果列表中未提供给定 SafetyCategory 的 SafetySetting，API 将使用相应类别的默认安全设置。支持的危害类别包括 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_CIVIC_INTEGRITY。如需详细了解可用的安全设置，请参阅指南。您还可以参阅安全指南，了解如何在 AI 应用中纳入安全考虑因素。

systemInstruction object (Content)

可选。开发者设置的系统指令。目前仅支持文本。

generationConfig object (GenerationConfig)

可选。模型生成和输出的配置选项。

cachedContent string

可选。用作提供预测的上下文的缓存内容的名称。格式：cachedContents/{cachedContent}

JSON 表示法 
{
  "model": string,
  "contents": [
    {
      object (Content)
    }
  ],
  "tools": [
    {
      object (Tool)
    }
  ],
  "toolConfig": {
    object (ToolConfig)
  },
  "safetySettings": [
    {
      object (SafetySetting)
    }
  ],
  "systemInstruction": {
    object (Content)
  },
  "generationConfig": {
    object (GenerationConfig)
  },
  "cachedContent": string
}

方法：models.asyncBatchEmbedContent

将一批 models.embedContent 个请求加入队列以进行批处理。我们在 GenerativeService 中有一个 models.batchEmbedContents 处理程序，但它是同步的。因此，我们将此变量命名为 Async，以免混淆。

端点

帖子 https://generativelanguage.googleapis.com/v1beta/{batch.model=models/*}:asyncBatchEmbedContent

路径参数

batch.model string

必需。用于生成补全的 Model 的名称。

格式：models/{model}。其格式为 models/{model}。

请求正文

请求正文中包含结构如下的数据：

字段
batch.name string

仅限输出。标识符。批次的资源名称。

格式：batches/{batchId}。

batch.displayName string

必需。相应批次的用户定义名称。

batch.inputConfig object (InputEmbedContentConfig)

必需。执行批量处理的实例的输入配置。

batch.output object (EmbedContentBatchOutput)

仅限输出。批量请求的输出。

batch.createTime string (Timestamp format)

仅限输出。批次的创建时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

batch.endTime string (Timestamp format)

仅限输出。批处理完成的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

batch.updateTime string (Timestamp format)

仅限输出。批次上次更新的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

batch.batchStats object (EmbedContentBatchStats)

仅限输出。有关批次的统计信息。

batch.state enum (BatchState)

仅限输出。批次的状态。

batch.priority string (int64 format)

可选。批次的优先级。优先级值较高的批次将先于优先级值较低的批次进行处理。允许使用负值。默认值为 0。

响应正文

如果成功，则响应正文包含一个 Operation 实例。

EmbedContentRequest

包含要嵌入的模型的 Content 的请求。

字段
model string

必需。模型的资源名称。用作模型使用的 ID。

此名称应与 models.list 方法返回的某个模型名称相匹配。

格式：models/{model}

content object (Content)

必需。要嵌入的内容。系统只会统计 parts.text 字段。

taskType enum (TaskType)

可选。嵌入将用于的可选任务类型。不支持较早的型号 (models/embedding-001)。

title string

可选。文本的可选标题。仅在 TaskType 为 RETRIEVAL_DOCUMENT 时适用。

注意：为 RETRIEVAL_DOCUMENT 指定 title 可提供质量更高的嵌入以用于检索。

outputDimensionality integer

可选。输出嵌入的可选降维。如果设置，则会从末尾截断输出嵌入中的过大值。仅受 2024 年之后推出的较新型号支持。如果使用较早的模型 (models/embedding-001)，则无法设置此值。

JSON 表示法 
{
  "model": string,
  "content": {
    object (Content)
  },
  "taskType": enum (TaskType),
  "title": string,
  "outputDimensionality": integer
}

方法：batches.get

获取长时间运行的操作的最新状态。客户端可以使用此方法，按 API 服务建议的时间间隔来轮询操作结果。

端点

get https://generativelanguage.googleapis.com/v1beta/{name=batches/*}

路径参数

name string

操作资源的名称。其格式为 batches/{batches}。

请求正文

请求正文必须为空。

响应正文

如果成功，则响应正文包含一个 Operation 实例。

方法：batches.list

列出与请求中指定的过滤条件匹配的操作。如果服务器不支持此方法，则会返回 UNIMPLEMENTED。

端点

get https://generativelanguage.googleapis.com/v1beta/{name=batches}

路径参数

name string

操作的父级资源名称。其格式为 batches。

查询参数

filter string

标准列表过滤条件。

pageSize integer

标准列表页面大小。

pageToken string

标准列表页面令牌。

请求正文

请求正文必须为空。

响应正文

如果成功，则响应正文包含一个 ListOperationsResponse 实例。

方法：batches.cancel

对长时间运行的操作启动异步取消。服务器会尽全力取消操作，但不能保证一定成功。如果服务器不支持此方法，则会返回 google.rpc.Code.UNIMPLEMENTED。客户端可以使用 Operations.GetOperation 或其他方法来检查操作是已成功取消还是仍然完成了。成功取消后，操作不会被删除，而会变成一个具有 Operation.error 值且 google.rpc.Status.code 为 1（对应于 Code.CANCELLED）的操作。

端点

帖子 https://generativelanguage.googleapis.com/v1beta/{name=batches/*}:cancel

路径参数

name string

要取消的操作资源的名称。其格式为 batches/{batches}。

请求正文

请求正文必须为空。

响应正文

如果成功，则响应正文为空的 JSON 对象。

方法：batches.delete

删除长时间运行的操作。此方法只是表明客户端不再关注操作结果，而不会取消操作。如果服务器不支持此方法，则会返回 google.rpc.Code.UNIMPLEMENTED。

端点

delete https://generativelanguage.googleapis.com/v1beta/{name=batches/*}

路径参数

name string

要删除的操作资源的名称。其格式为 batches/{batches}。

请求正文

请求正文必须为空。

响应正文

如果成功，则响应正文为空的 JSON 对象。

GenerateContentBatch

表示一批 GenerateContent 请求的资源。

字段
model string

必需。用于生成补全的 Model 的名称。

格式：models/{model}。

name string

仅限输出。标识符。批次的资源名称。

格式：batches/{batchId}。

displayName string

必需。相应批次的用户定义名称。

inputConfig object (InputConfig)

必需。执行批量处理的实例的输入配置。

output object (GenerateContentBatchOutput)

仅限输出。批量请求的输出。

createTime string (Timestamp format)

仅限输出。批次的创建时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

endTime string (Timestamp format)

仅限输出。批处理完成的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

updateTime string (Timestamp format)

仅限输出。批次上次更新的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

batchStats object (BatchStats)

仅限输出。有关批次的统计信息。

state enum (BatchState)

仅限输出。批次的状态。

priority string (int64 format)

可选。批次的优先级。优先级值较高的批次将先于优先级值较低的批次进行处理。允许使用负值。默认值为 0。

JSON 表示法 
{
  "model": string,
  "name": string,
  "displayName": string,
  "inputConfig": {
    object (InputConfig)
  },
  "output": {
    object (GenerateContentBatchOutput)
  },
  "createTime": string,
  "endTime": string,
  "updateTime": string,
  "batchStats": {
    object (BatchStats)
  },
  "state": enum (BatchState),
  "priority": string
}

InputConfig

配置批量请求的输入。

字段
source Union type
必需。输入的来源。source 只能是下列其中一项：
fileName string

包含输入请求的 File 的名称。

requests object (InlinedRequests)

批次中要处理的请求。

JSON 表示法 
{

  // source
  "fileName": string,
  "requests": {
    object (InlinedRequests)
  }
  // Union type
}

InlinedRequests

如果作为批次创建请求的一部分提供，则为要在批次中处理的请求。

字段
requests[] object (InlinedRequest)

必需。批次中要处理的请求。

JSON 表示法 
{
  "requests": [
    {
      object (InlinedRequest)
    }
  ]
}

InlinedRequest

要在批处理中处理的请求。

字段
request object (GenerateContentRequest)

必需。要在批处理中处理的请求。

metadata object (Struct format)

可选。要与请求相关联的元数据。

JSON 表示法 
{
  "request": {
    object (GenerateContentRequest)
  },
  "metadata": {
    object
  }
}

GenerateContentBatchOutput

批量请求的输出。此值在 BatchGenerateContentResponse 或 GenerateContentBatch.output 字段中返回。

字段
output Union type
批量请求的输出。output 只能是下列其中一项：
responsesFile string

仅限输出。包含回答内容的文件对应的文件 ID。该文件将是一个 JSONL 文件，每行包含一个回答。响应将是采用 JSON 格式的 GenerateContentResponse 消息。响应将按输入请求的顺序写入。

inlinedResponses object (InlinedResponses)

仅限输出。对批处理请求的响应。当批处理是使用内嵌请求构建时返回。响应的顺序与输入请求的顺序相同。

JSON 表示法 
{

  // output
  "responsesFile": string,
  "inlinedResponses": {
    object (InlinedResponses)
  }
  // Union type
}

InlinedResponses

对批处理请求的响应。

字段
inlinedResponses[] object (InlinedResponse)

仅限输出。对批处理请求的响应。

JSON 表示法 
{
  "inlinedResponses": [
    {
      object (InlinedResponse)
    }
  ]
}

InlinedResponse

对批处理中单个请求的响应。

字段
metadata object (Struct format)

仅限输出。与请求相关联的元数据。

output Union type
请求的输出。output 只能是下列其中一项：
error object (Status)

仅限输出。处理请求时遇到的错误。

response object (GenerateContentResponse)

仅限输出。对请求的响应。

JSON 表示法 
{
  "metadata": {
    object
  },

  // output
  "error": {
    object (Status)
  },
  "response": {
    object (GenerateContentResponse)
  }
  // Union type
}

BatchStats

有关批次的统计信息。

字段
requestCount string (int64 format)

仅限输出。批次中的请求数量。

successfulRequestCount string (int64 format)

仅限输出。成功处理的请求数。

failedRequestCount string (int64 format)

仅限输出。未能成功处理的请求数。

pendingRequestCount string (int64 format)

仅限输出。仍处于待处理状态的请求数。

JSON 表示法 
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}

EmbedContentBatch

表示一批 EmbedContent 请求的资源。

字段
model string

必需。用于生成补全的 Model 的名称。

格式：models/{model}。

name string

仅限输出。标识符。批次的资源名称。

格式：batches/{batchId}。

displayName string

必需。相应批次的用户定义名称。

inputConfig object (InputEmbedContentConfig)

必需。执行批量处理的实例的输入配置。

output object (EmbedContentBatchOutput)

仅限输出。批量请求的输出。

createTime string (Timestamp format)

仅限输出。批次的创建时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

endTime string (Timestamp format)

仅限输出。批处理完成的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

updateTime string (Timestamp format)

仅限输出。批次上次更新的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

batchStats object (EmbedContentBatchStats)

仅限输出。有关批次的统计信息。

state enum (BatchState)

仅限输出。批次的状态。

priority string (int64 format)

可选。批次的优先级。优先级值较高的批次将先于优先级值较低的批次进行处理。允许使用负值。默认值为 0。

JSON 表示法 
{
  "model": string,
  "name": string,
  "displayName": string,
  "inputConfig": {
    object (InputEmbedContentConfig)
  },
  "output": {
    object (EmbedContentBatchOutput)
  },
  "createTime": string,
  "endTime": string,
  "updateTime": string,
  "batchStats": {
    object (EmbedContentBatchStats)
  },
  "state": enum (BatchState),
  "priority": string
}

InputEmbedContentConfig

配置批量请求的输入。

字段
source Union type
必需。输入的来源。source 只能是下列其中一项：
fileName string

包含输入请求的 File 的名称。

requests object (InlinedEmbedContentRequests)

批次中要处理的请求。

JSON 表示法 
{

  // source
  "fileName": string,
  "requests": {
    object (InlinedEmbedContentRequests)
  }
  // Union type
}

InlinedEmbedContentRequests

如果作为批次创建请求的一部分提供，则为要在批次中处理的请求。

字段
requests[] object (InlinedEmbedContentRequest)

必需。批次中要处理的请求。

JSON 表示法 
{
  "requests": [
    {
      object (InlinedEmbedContentRequest)
    }
  ]
}

InlinedEmbedContentRequest

要在批处理中处理的请求。

字段
request object (EmbedContentRequest)

必需。要在批处理中处理的请求。

metadata object (Struct format)

可选。要与请求相关联的元数据。

JSON 表示法 
{
  "request": {
    object (EmbedContentRequest)
  },
  "metadata": {
    object
  }
}

EmbedContentBatchOutput

批量请求的输出。此值在 AsyncBatchEmbedContentResponse 或 EmbedContentBatch.output 字段中返回。

字段
output Union type
批量请求的输出。output 只能是下列其中一项：
responsesFile string

仅限输出。包含回答内容的文件对应的文件 ID。该文件将是一个 JSONL 文件，每行包含一个回答。响应将是采用 JSON 格式的 EmbedContentResponse 消息。响应将按输入请求的顺序写入。

inlinedResponses object (InlinedEmbedContentResponses)

仅限输出。对批处理请求的响应。当批处理是使用内嵌请求构建时返回。响应的顺序与输入请求的顺序相同。

JSON 表示法 
{

  // output
  "responsesFile": string,
  "inlinedResponses": {
    object (InlinedEmbedContentResponses)
  }
  // Union type
}

InlinedEmbedContentResponses

对批处理请求的响应。

字段
inlinedResponses[] object (InlinedEmbedContentResponse)

仅限输出。对批处理请求的响应。

JSON 表示法 
{
  "inlinedResponses": [
    {
      object (InlinedEmbedContentResponse)
    }
  ]
}

InlinedEmbedContentResponse

对批处理中单个请求的响应。

字段
metadata object (Struct format)

仅限输出。与请求相关联的元数据。

output Union type
请求的输出。output 只能是下列其中一项：
error object (Status)

仅限输出。处理请求时遇到的错误。

response object (EmbedContentResponse)

仅限输出。对请求的响应。

JSON 表示法 
{
  "metadata": {
    object
  },

  // output
  "error": {
    object (Status)
  },
  "response": {
    object (EmbedContentResponse)
  }
  // Union type
}

EmbedContentBatchStats

有关批次的统计信息。

字段
requestCount string (int64 format)

仅限输出。批次中的请求数量。

successfulRequestCount string (int64 format)

仅限输出。成功处理的请求数。

failedRequestCount string (int64 format)

仅限输出。未能成功处理的请求数。

pendingRequestCount string (int64 format)

仅限输出。仍处于待处理状态的请求数。

JSON 表示法 
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}

BatchState

批次的状态。

枚举
BATCH_STATE_UNSPECIFIED 未指定批处理状态。
BATCH_STATE_PENDING 服务正在准备运行批处理。
BATCH_STATE_RUNNING 批次正在进行中。
BATCH_STATE_SUCCEEDED 相应批次已成功完成。
BATCH_STATE_FAILED 批次失败。
BATCH_STATE_CANCELLED 批次已取消。
BATCH_STATE_EXPIRED 相应批次已过期。

REST 资源：batches

资源：Operation

此资源表示由网络 API 调用引发的长时间运行的操作。

字段
name string

由服务器分配的名称，该名称仅在最初返回它的那项服务中是唯一的。如果您使用默认 HTTP 映射，则 name 应是以 operations/{unique_id} 结尾的资源名称。

metadata object

与操作关联的服务专属元数据。它通常包含进度信息和常见元数据（如创建时间）。一些服务可能不会提供此类元数据。任何返回长时间运行操作的方法都应记录元数据类型（如果有的话）。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

done boolean

如果值为 false，则表示操作仍在进行中。如果为 true，则表示操作已完成，其结果不是 error 就是 response。

result Union type
操作结果，可以是 error，也可以是有效的 response。如果 done == false，则既不会设置 error，也不会设置 response。如果 done == true，则只能设置 error 或 response 中的一项。部分服务可能不会提供结果。result 只能是下列其中一项：
error object (Status)

操作失败或被取消时表示有错误发生的结果。

response object

操作的常规成功响应。如果原始方法在成功时不返回任何数据（如 Delete），则响应为 google.protobuf.Empty。如果原始方法为标准 Get/Create/Update 方法，则响应应该为资源。对于其他方法，响应类型应为 XxxResponse，其中 Xxx 是原始方法的名称。例如，如果原始方法名称为 TakeSnapshot()，则推断的响应类型为 TakeSnapshotResponse。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

JSON 表示法 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}