Batch Mode

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

候选人

模型生成的回答候选对象。

字段
content object (Content)

仅限输出。模型返回的生成内容。

finishReason enum (FinishReason)

可选。仅限输出。模型停止生成词元的原因。

如果为空，则模型尚未停止生成令牌。

safetyRatings[] object (SafetyRating)

候选回答的安全评分列表。

每个类别最多只能有一个分级。

citationMetadata object (CitationMetadata)

仅限输出。模型生成的候选回答的引用信息。

此字段可能会填充 content 中包含的任何文本的朗读信息。这些段落是从基础 LLM 的训练数据中的受版权保护的内容“背诵”出来的。

tokenCount integer

仅限输出。相应候选对象的令牌数量。

groundingAttributions[] object (GroundingAttribution)

仅限输出。为有依据的答案做出贡献的来源的提供方信息。

系统会针对 GenerateAnswer 调用填充此字段。

groundingMetadata object (GroundingMetadata)

仅限输出。候选对象的 grounding 元数据。

系统会针对 GenerateContent 调用填充此字段。

avgLogprobs number

仅限输出。候选者的平均对数概率得分。

logprobsResult object (LogprobsResult)

仅限输出。回答 token 和热门 token 的对数似然得分

urlContextMetadata object (UrlContextMetadata)

仅限输出。与网址上下文检索工具相关的元数据。

index integer

仅限输出。响应候选列表中的候选索引。

JSON 表示法 
{
  "content": {
    object (Content)
  },
  "finishReason": enum (FinishReason),
  "safetyRatings": [
    {
      object (SafetyRating)
    }
  ],
  "citationMetadata": {
    object (CitationMetadata)
  },
  "tokenCount": integer,
  "groundingAttributions": [
    {
      object (GroundingAttribution)
    }
  ],
  "groundingMetadata": {
    object (GroundingMetadata)
  },
  "avgLogprobs": number,
  "logprobsResult": {
    object (LogprobsResult)
  },
  "urlContextMetadata": {
    object (UrlContextMetadata)
  },
  "index": integer
}

FinishReason

定义模型停止生成令牌的原因。

枚举
FINISH_REASON_UNSPECIFIED 默认值。此值未使用。
STOP 模型的自然停止点或提供的停止序列。
MAX_TOKENS 已达到请求中指定的 token 数量上限。
SAFETY 出于安全原因，回答候选内容被标记。
RECITATION 回答候选内容因背诵原因而被标记。
LANGUAGE 系统标记了候选回答内容，原因是其使用了不受支持的语言。
OTHER 原因未知。
BLOCKLIST 由于内容包含禁用词，因此 token 生成操作已停止。
PROHIBITED_CONTENT 由于可能包含禁止的内容，因此 token 生成操作已停止。
SPII 由于内容可能包含敏感的个人身份信息 (SPII)，因此 token 生成操作已停止。
MALFORMED_FUNCTION_CALL 模型生成的函数调用无效。
IMAGE_SAFETY 由于生成的图片包含违规内容，因此 token 生成已停止。
UNEXPECTED_TOOL_CALL 模型生成了工具调用，但请求中未启用任何工具。

GroundingAttribution

对促成回答的来源的提供方信息。

字段
sourceId object (AttributionSourceId)

仅限输出。促成相应归因的来源的标识符。

content object (Content)

构成此提供方信息的依据来源内容。

JSON 表示法 
{
  "sourceId": {
    object (AttributionSourceId)
  },
  "content": {
    object (Content)
  }
}

AttributionSourceId

促成相应归因的来源的标识符。

字段
source Union type
source 只能是下列其中一项：
groundingPassage object (GroundingPassageId)

内嵌段落的标识符。

semanticRetrieverChunk object (SemanticRetrieverChunk)

通过语义检索器提取的 Chunk 的标识符。

JSON 表示法 
{

  // source
  "groundingPassage": {
    object (GroundingPassageId)
  },
  "semanticRetrieverChunk": {
    object (SemanticRetrieverChunk)
  }
  // Union type
}

GroundingPassageId

GroundingPassage 中某个部分的标识符。

字段
passageId string

仅限输出。与 GenerateAnswerRequest 的 GroundingPassage.id 匹配的段落的 ID。

partIndex integer

仅限输出。GenerateAnswerRequest 的 GroundingPassage.content 中相应部分的索引。

JSON 表示法 
{
  "passageId": string,
  "partIndex": integer
}

SemanticRetrieverChunk

通过 SemanticRetrieverConfig 使用 GenerateAnswerRequest 中指定的语义检索器检索到的 Chunk 的标识符。

字段
source string

仅限输出。与请求的 SemanticRetrieverConfig.source 匹配的来源的名称。示例：corpora/123 或 corpora/123/documents/abc

chunk string

仅限输出。包含归因文本的 Chunk 的名称。示例：corpora/123/documents/abc/chunks/xyz

JSON 表示法 
{
  "source": string,
  "chunk": string
}

GroundingMetadata

启用 grounding 后返回给客户端的元数据。

字段
groundingChunks[] object (GroundingChunk)

从指定的事实依据来源检索到的佐证参考资料列表。

groundingSupports[] object (GroundingSupport)

基础支持列表。

webSearchQueries[] string

后续网页搜索的网页搜索查询。

searchEntryPoint object (SearchEntryPoint)

可选。Google 搜索条目，用于后续的网页搜索。

retrievalMetadata object (RetrievalMetadata)

与接地流程中的检索相关的元数据。

JSON 表示法 
{
  "groundingChunks": [
    {
      object (GroundingChunk)
    }
  ],
  "groundingSupports": [
    {
      object (GroundingSupport)
    }
  ],
  "webSearchQueries": [
    string
  ],
  "searchEntryPoint": {
    object (SearchEntryPoint)
  },
  "retrievalMetadata": {
    object (RetrievalMetadata)
  }
}

SearchEntryPoint

Google 搜索入口点。

字段
renderedContent string

可选。可嵌入网页或应用 WebView 中的 Web 内容代码段。

sdkBlob string (bytes format)

可选。以 Base64 编码的 JSON，表示 <搜索字词、搜索网址> 元组的数组。

使用 base64 编码的字符串。

JSON 表示法 
{
  "renderedContent": string,
  "sdkBlob": string
}

GroundingChunk

接地块。

字段
chunk_type Union type
分块类型。chunk_type 只能是下列其中一项：
web object (Web)

来自网络的接地块。

JSON 表示法 
{

  // chunk_type
  "web": {
    object (Web)
  }
  // Union type
}

Web

来自网络的块。

字段
uri string

块的 URI 引用。

title string

块的标题。

JSON 表示法 
{
  "uri": string,
  "title": string
}

GroundingSupport

接地支持。

字段
groundingChunkIndices[] integer

一个索引（指向“grounding_chunk”）列表，用于指定与声明关联的引用。例如，[1,3,4] 表示 grounding_chunk[1]、grounding_chunk[3]、grounding_chunk[4] 是归因于相应声明的检索到的内容。

confidenceScores[] number

支持参考的置信度分数。范围为 0 到 1。1 表示最有信心。此列表的大小必须与 groundingChunkIndices 相同。

segment object (Segment)

相应支持所涉及的内容片段。

JSON 表示法 
{
  "groundingChunkIndices": [
    integer
  ],
  "confidenceScores": [
    number
  ],
  "segment": {
    object (Segment)
  }
}

Segment

内容片段。

字段
partIndex integer

仅限输出。Part 对象在其父 Content 对象中的索引。

startIndex integer

仅限输出。指定 Part 中的起始索引（以字节为单位）。从 Part 开始处的偏移量（含），从零开始。

endIndex integer

仅限输出。指定 Part 中的结束索引（以字节为单位）。从相应部分的开头开始的偏移量（不含边界值），从零开始。

text string

仅限输出。响应中与相应片段对应的文本。

JSON 表示法 
{
  "partIndex": integer,
  "startIndex": integer,
  "endIndex": integer,
  "text": string
}

RetrievalMetadata

与接地流程中的检索相关的元数据。

字段
googleSearchDynamicRetrievalScore number

可选。一个分数，用于指示 Google 搜索中的信息可能有助于回答提示的程度。得分介于 [0, 1] 范围内，其中 0 表示可能性最低，1 表示可能性最高。仅当启用 Google 搜索接地和动态检索时，系统才会填充此得分。系统会将该值与阈值进行比较，以确定是否触发 Google 搜索。

JSON 表示法 
{
  "googleSearchDynamicRetrievalScore": number
}

LogprobsResult

Logprobs 结果

字段
topCandidates[] object (TopCandidates)

长度 = 解码步总数。

chosenCandidates[] object (Candidate)

长度 = 解码步总数。所选候选词元可能位于 topCandidates 中，也可能不在其中。

JSON 表示法 
{
  "topCandidates": [
    {
      object (TopCandidates)
    }
  ],
  "chosenCandidates": [
    {
      object (Candidate)
    }
  ]
}

TopCandidates

每个解码步骤中具有最高对数概率的候选对象。

字段
candidates[] object (Candidate)

按对数概率降序排序。

JSON 表示法 
{
  "candidates": [
    {
      object (Candidate)
    }
  ]
}

候选人

logprobs 令牌和得分的候选对象。

字段
token string

候选人的令牌字符串值。

tokenId integer

候选人的令牌 ID 值。

logProbability number

候选词元的对数概率。

JSON 表示法 
{
  "token": string,
  "tokenId": integer,
  "logProbability": number
}

UrlContextMetadata

与网址上下文检索工具相关的元数据。

字段
urlMetadata[] object (UrlMetadata)

网址上下文列表。

JSON 表示法 
{
  "urlMetadata": [
    {
      object (UrlMetadata)
    }
  ]
}

UrlMetadata

单个网址检索的上下文。

字段
retrievedUrl string

由工具检索到的网址。

urlRetrievalStatus enum (UrlRetrievalStatus)

网址检索的状态。

JSON 表示法 
{
  "retrievedUrl": string,
  "urlRetrievalStatus": enum (UrlRetrievalStatus)
}

UrlRetrievalStatus

网址检索的状态。

枚举
URL_RETRIEVAL_STATUS_UNSPECIFIED 默认值。此值未使用。
URL_RETRIEVAL_STATUS_SUCCESS 网址检索成功。
URL_RETRIEVAL_STATUS_ERROR 由于出错，网址检索失败。

CitationMetadata

一段内容的一组来源提供方信息。

字段
citationSources[] object (CitationSource)

特定回答的来源引用。

JSON 表示法 
{
  "citationSources": [
    {
      object (CitationSource)
    }
  ]
}

CitationSource

对特定回答的部分内容所引用来源的引用。

字段
startIndex integer

可选。归因于相应来源的回答部分的起始位置。

索引表示分段的起始位置（以字节为单位）。

endIndex integer

可选。归因细分的结束时间（不含）。

uri string

可选。被归因于部分文本的来源的 URI。

license string

可选。被归因于细分的 GitHub 项目的许可。

代码引用必须包含许可信息。

JSON 表示法 
{
  "startIndex": integer,
  "endIndex": integer,
  "uri": string,
  "license": string
}

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 对象。