Batch Mode

Gemini 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/{batch_id}。

batch.displayName string

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

batch.inputConfig object (InputConfig)

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

batch.output object (GenerateContentBatchOutput)

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

batch.createTime string (Timestamp format)

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

采用 RFC 3339 标准，生成的输出将始终在末尾带 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，并使用 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，并使用 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
}

GenerateContentBatch

一种资源，用于表示一批 GenerateContent 请求。

字段
model string

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

格式：models/{model}。

name string

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

格式：batches/{batch_id}。

displayName string

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

inputConfig object (InputConfig)

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

output object (GenerateContentBatchOutput)

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

createTime string (Timestamp format)

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

采用 RFC 3339 标准，生成的输出将始终在末尾带 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，并使用 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，并使用 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
}

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
}

方法：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 对象。