Batch Mode

The Gemini API supports batch mode, which lets you process multiple requests in a single call. For more details, see the Batch mode guide.

Candidate

A response candidate generated from the model.

Fields
content object (Content)

Output only. Generated content returned from the model.

finishReason enum (FinishReason)

Optional. Output only. The reason why the model stopped generating tokens.

If empty, the model has not stopped generating tokens.

safetyRatings[] object (SafetyRating)

List of ratings for the safety of a response candidate.

There is at most one rating per category.

citationMetadata object (CitationMetadata)

Output only. Citation information for model-generated candidate.

This field may be populated with recitation information for any text included in the content. These are passages that are "recited" from copyrighted material in the foundational LLM's training data.

tokenCount integer

Output only. Token count for this candidate.

groundingAttributions[] object (GroundingAttribution)

Output only. Attribution information for sources that contributed to a grounded answer.

This field is populated for GenerateAnswer calls.

groundingMetadata object (GroundingMetadata)

Output only. Grounding metadata for the candidate.

This field is populated for GenerateContent calls.

avgLogprobs number

Output only. Average log probability score of the candidate.

logprobsResult object (LogprobsResult)

Output only. Log-likelihood scores for the response tokens and top tokens

urlContextMetadata object (UrlContextMetadata)

Output only. Metadata related to url context retrieval tool.

index integer

Output only. Index of the candidate in the list of response candidates.

JSON representation 
{
  "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

Defines the reason why the model stopped generating tokens.

Enums
FINISH_REASON_UNSPECIFIED Default value. This value is unused.
STOP Natural stop point of the model or provided stop sequence.
MAX_TOKENS The maximum number of tokens as specified in the request was reached.
SAFETY The response candidate content was flagged for safety reasons.
RECITATION The response candidate content was flagged for recitation reasons.
LANGUAGE The response candidate content was flagged for using an unsupported language.
OTHER Unknown reason.
BLOCKLIST Token generation stopped because the content contains forbidden terms.
PROHIBITED_CONTENT Token generation stopped for potentially containing prohibited content.
SPII Token generation stopped because the content potentially contains Sensitive Personally Identifiable Information (SPII).
MALFORMED_FUNCTION_CALL The function call generated by the model is invalid.
IMAGE_SAFETY Token generation stopped because generated images contain safety violations.

GroundingAttribution

Attribution for a source that contributed to an answer.

Fields
sourceId object (AttributionSourceId)

Output only. Identifier for the source contributing to this attribution.

content object (Content)

Grounding source content that makes up this attribution.

JSON representation 
{
  "sourceId": {
    object (AttributionSourceId)
  },
  "content": {
    object (Content)
  }
}

AttributionSourceId

Identifier for the source contributing to this attribution.

Fields
source Union type
source can be only one of the following:
groundingPassage object (GroundingPassageId)

Identifier for an inline passage.

semanticRetrieverChunk object (SemanticRetrieverChunk)

Identifier for a Chunk fetched via Semantic Retriever.

JSON representation 
{

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

GroundingPassageId

Identifier for a part within a GroundingPassage.

Fields
passageId string

Output only. ID of the passage matching the GenerateAnswerRequest's GroundingPassage.id.

partIndex integer

Output only. Index of the part within the GenerateAnswerRequest's GroundingPassage.content.

JSON representation 
{
  "passageId": string,
  "partIndex": integer
}

SemanticRetrieverChunk

Identifier for a Chunk retrieved via Semantic Retriever specified in the GenerateAnswerRequest using SemanticRetrieverConfig.

Fields
source string

Output only. Name of the source matching the request's SemanticRetrieverConfig.source. Example: corpora/123 or corpora/123/documents/abc

chunk string

Output only. Name of the Chunk containing the attributed text. Example: corpora/123/documents/abc/chunks/xyz

JSON representation 
{
  "source": string,
  "chunk": string
}

GroundingMetadata

Metadata returned to client when grounding is enabled.

Fields
groundingChunks[] object (GroundingChunk)

List of supporting references retrieved from specified grounding source.

groundingSupports[] object (GroundingSupport)

List of grounding support.

webSearchQueries[] string

Web search queries for the following-up web search.

searchEntryPoint object (SearchEntryPoint)

Optional. Google search entry for the following-up web searches.

retrievalMetadata object (RetrievalMetadata)

Metadata related to retrieval in the grounding flow.

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

SearchEntryPoint

Google search entry point.

Fields
renderedContent string

Optional. Web content snippet that can be embedded in a web page or an app webview.

sdkBlob string (bytes format)

Optional. Base64 encoded JSON representing array of <search term, search url> tuple.

A base64-encoded string.

JSON representation 
{
  "renderedContent": string,
  "sdkBlob": string
}

GroundingChunk

Grounding chunk.

Fields
chunk_type Union type
Chunk type. chunk_type can be only one of the following:
web object (Web)

Grounding chunk from the web.

JSON representation 
{

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

Web

Chunk from the web.

Fields
uri string

URI reference of the chunk.

title string

Title of the chunk.

JSON representation 
{
  "uri": string,
  "title": string
}

GroundingSupport

Grounding support.

Fields
groundingChunkIndices[] integer

A list of indices (into 'grounding_chunk') specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim.

confidenceScores[] number

Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the groundingChunkIndices.

segment object (Segment)

Segment of the content this support belongs to.

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

Segment

Segment of the content.

Fields
partIndex integer

Output only. The index of a Part object within its parent Content object.

startIndex integer

Output only. Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero.

endIndex integer

Output only. End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero.

text string

Output only. The text corresponding to the segment from the response.

JSON representation 
{
  "partIndex": integer,
  "startIndex": integer,
  "endIndex": integer,
  "text": string
}

RetrievalMetadata

Metadata related to retrieval in the grounding flow.

Fields
googleSearchDynamicRetrievalScore number

Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger google search.

JSON representation 
{
  "googleSearchDynamicRetrievalScore": number
}

LogprobsResult

Logprobs Result

Fields
topCandidates[] object (TopCandidates)

Length = total number of decoding steps.

chosenCandidates[] object (Candidate)

Length = total number of decoding steps. The chosen candidates may or may not be in topCandidates.

JSON representation 
{
  "topCandidates": [
    {
      object (TopCandidates)
    }
  ],
  "chosenCandidates": [
    {
      object (Candidate)
    }
  ]
}

TopCandidates

Candidates with top log probabilities at each decoding step.

Fields
candidates[] object (Candidate)

Sorted by log probability in descending order.

JSON representation 
{
  "candidates": [
    {
      object (Candidate)
    }
  ]
}

Candidate

Candidate for the logprobs token and score.

Fields
token string

The candidate’s token string value.

tokenId integer

The candidate’s token id value.

logProbability number

The candidate's log probability.

JSON representation 
{
  "token": string,
  "tokenId": integer,
  "logProbability": number
}

UrlContextMetadata

Metadata related to url context retrieval tool.

Fields
urlMetadata[] object (UrlMetadata)

List of url context.

JSON representation 
{
  "urlMetadata": [
    {
      object (UrlMetadata)
    }
  ]
}

UrlMetadata

Context of the a single url retrieval.

Fields
retrievedUrl string

Retrieved url by the tool.

urlRetrievalStatus enum (UrlRetrievalStatus)

Status of the url retrieval.

JSON representation 
{
  "retrievedUrl": string,
  "urlRetrievalStatus": enum (UrlRetrievalStatus)
}

UrlRetrievalStatus

Status of the url retrieval.

Enums
URL_RETRIEVAL_STATUS_UNSPECIFIED Default value. This value is unused.
URL_RETRIEVAL_STATUS_SUCCESS Url retrieval is successful.
URL_RETRIEVAL_STATUS_ERROR Url retrieval is failed due to error.

CitationMetadata

A collection of source attributions for a piece of content.

Fields
citationSources[] object (CitationSource)

Citations to sources for a specific response.

JSON representation 
{
  "citationSources": [
    {
      object (CitationSource)
    }
  ]
}

CitationSource

A citation to a source for a portion of a specific response.

Fields
startIndex integer

Optional. Start of segment of the response that is attributed to this source.

Index indicates the start of the segment, measured in bytes.

endIndex integer

Optional. End of the attributed segment, exclusive.

uri string

Optional. URI that is attributed as a source for a portion of the text.

license string

Optional. License for the GitHub project that is attributed as a source for segment.

License info is required for code citations.

JSON representation 
{
  "startIndex": integer,
  "endIndex": integer,
  "uri": string,
  "license": string
}

REST Resource: batches

Resource: Operation

This resource represents a long-running operation that is the result of a network API call.

Fields
name string

The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should be a resource name ending with operations/{unique_id}.

metadata object

Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata. Any method that returns a long-running operation should document the metadata type, if any.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

done boolean

If the value is false, it means the operation is still in progress. If true, the operation is completed, and either error or response is available.

result Union type
The operation result, which can be either an error or a valid response. If done == false, neither error nor response is set. If done == true, exactly one of error or response can be set. Some services might not provide the result. result can be only one of the following:
error object (Status)

The error result of the operation in case of failure or cancellation.

response object

The normal, successful response of the operation. If the original method returns no data on success, such as Delete, the response is google.protobuf.Empty. If the original method is standard Get/Create/Update, the response should be the resource. For other methods, the response should have the type XxxResponse, where Xxx is the original method name. For example, if the original method name is TakeSnapshot(), the inferred response type is TakeSnapshotResponse.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

JSON representation 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

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

Method: batches.get

Gets the latest state of a long-running operation. Clients can use this method to poll the operation result at intervals as recommended by the API service.

Endpoint

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

Path parameters

name string

The name of the operation resource. It takes the form batches/{batches}.

Request body

The request body must be empty.

Response body

If successful, the response body contains an instance of Operation.

Method: batches.list

Lists operations that match the specified filter in the request. If the server doesn't support this method, it returns UNIMPLEMENTED.

Endpoint

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

Path parameters

name string

The name of the operation's parent resource. It takes the form batches.

Query parameters

filter string

The standard list filter.

pageSize integer

The standard list page size.

pageToken string

The standard list page token.

Request body

The request body must be empty.

Response body

If successful, the response body contains an instance of ListOperationsResponse.

Method: batches.cancel

Starts asynchronous cancellation on a long-running operation. The server makes a best effort to cancel the operation, but success is not guaranteed. If the server doesn't support this method, it returns google.rpc.Code.UNIMPLEMENTED. Clients can use Operations.GetOperation or other methods to check whether the cancellation succeeded or whether the operation completed despite cancellation. On successful cancellation, the operation is not deleted; instead, it becomes an operation with an Operation.error value with a google.rpc.Status.code of 1, corresponding to Code.CANCELLED.

Endpoint

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

Path parameters

name string

The name of the operation resource to be cancelled. It takes the form batches/{batches}.

Request body

The request body must be empty.

Response body

If successful, the response body is an empty JSON object.

Method: batches.delete

Deletes a long-running operation. This method indicates that the client is no longer interested in the operation result. It does not cancel the operation. If the server doesn't support this method, it returns google.rpc.Code.UNIMPLEMENTED.

Endpoint

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

Path parameters

name string

The name of the operation resource to be deleted. It takes the form batches/{batches}.

Request body

The request body must be empty.

Response body

If successful, the response body is an empty JSON object.