GenerateContentResponse

Response message for [PredictionService.GenerateContent].

Fields
candidates[] object (Candidate)

Output only. Generated candidates.

modelVersion string

Output only. The model version used to generate the response.

createTime string (Timestamp format)

Output only. timestamp when the request is made to the server.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

responseId string

Output only. responseId is used to identify each response. It is the encoding of the eventId.

promptFeedback object (PromptFeedback)

Output only. Content filter results for a prompt sent in the request. Note: Sent only in the first stream chunk. Only happens when no candidates were generated due to content violations.

usageMetadata object (UsageMetadata)

Usage metadata about the response(s).

JSON representation 
{
  "candidates": [
    {
      object (Candidate)
    }
  ],
  "modelVersion": string,
  "createTime": string,
  "responseId": string,
  "promptFeedback": {
    object (PromptFeedback)
  },
  "usageMetadata": {
    object (UsageMetadata)
  }
}

Candidate

A response candidate generated from the model.

Fields
index integer

Output only. The 0-based index of this candidate in the list of generated responses. This is useful for distinguishing between multiple candidates when candidateCount > 1.

content object (Content)

Output only. The content of the candidate.

avgLogprobs number

Output only. The average log probability of the tokens in this candidate. This is a length-normalized score that can be used to compare the quality of candidates of different lengths. A higher average log probability suggests a more confident and coherent response.

logprobsResult object (LogprobsResult)

Output only. The detailed log probability information for the tokens in this candidate. This is useful for debugging, understanding model uncertainty, and identifying potential "hallucinations".

finishReason enum (FinishReason)

Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating.

safetyRatings[] object (SafetyRating)

Output only. A list of ratings for the safety of a response candidate.

There is at most one rating per category.

citationMetadata object (CitationMetadata)

Output only. A collection of citations that apply to the generated content.

groundingMetadata object (GroundingMetadata)

Output only. metadata returned when grounding is enabled. It contains the sources used to ground the generated content.

urlContextMetadata object (UrlContextMetadata)

Output only. metadata returned when the model uses the urlContext tool to get information from a user-provided URL.

finishMessage string

Output only. Describes the reason the model stopped generating tokens in more detail. This field is returned only when finishReason is set.

JSON representation 
{
  "index": integer,
  "content": {
    object (Content)
  },
  "avgLogprobs": number,
  "logprobsResult": {
    object (LogprobsResult)
  },
  "finishReason": enum (FinishReason),
  "safetyRatings": [
    {
      object (SafetyRating)
    }
  ],
  "citationMetadata": {
    object (CitationMetadata)
  },
  "groundingMetadata": {
    object (GroundingMetadata)
  },
  "urlContextMetadata": {
    object (UrlContextMetadata)
  },
  "finishMessage": string
}

LogprobsResult

The log probabilities of the tokens generated by the model.

This is useful for understanding the model's confidence in its predictions and for debugging. For example, you can use log probabilities to identify when the model is making a less confident prediction or to explore alternative responses that the model considered. A low log probability can also indicate that the model is "hallucinating" or generating factually incorrect information.

Fields
topCandidates[] object (TopCandidates)

A list of the top candidate tokens at each decoding step. The length of this list is equal to the total number of decoding steps.

chosenCandidates[] object (Candidate)

A list of the chosen candidate tokens at each decoding step. The length of this list is equal to the total number of decoding steps. Note that the chosen candidate might not be in topCandidates.

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

TopCandidates

A list of the top candidate tokens and their log probabilities at each decoding step. This can be used to see what other tokens the model considered.

Fields
candidates[] object (Candidate)

The list of candidate tokens, sorted by log probability in descending order.

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

Candidate

A single token and its associated log probability.

Fields
token string

The token's string representation.

tokenId integer

The token's numerical id. While the token field provides the string representation of the token, the tokenId is the numerical representation that the model uses internally. This can be useful for developers who want to build custom logic based on the model's vocabulary.

logProbability number

The log probability of this token. A higher value indicates that the model was more confident in this token. The log probability can be used to assess the relative likelihood of different tokens and to identify when the model is uncertain.

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

FinishReason

The reason why the model stopped generating tokens. If this field is empty, the model has not stopped generating.

Enums
FINISH_REASON_UNSPECIFIED The finish reason is unspecified.
STOP The model reached a natural stopping point or a configured stop sequence.
MAX_TOKENS The model generated the maximum number of tokens allowed by the maxOutputTokens parameter.
SAFETY The model stopped generating because the content potentially violates safety policies. NOTE: When streaming, the content field is empty if content filters block the output.
RECITATION The model stopped generating because the content may be a recitation from a source.
OTHER The model stopped generating for a reason not otherwise specified.
BLOCKLIST The model stopped generating because the content contains a term from a configured blocklist.
PROHIBITED_CONTENT The model stopped generating because the content may be prohibited.
SPII The model stopped generating because the content may contain sensitive personally identifiable information (SPII).
MALFORMED_FUNCTION_CALL The model generated a function call that is syntactically invalid and can't be parsed.
MODEL_ARMOR The model response was blocked by Model Armor.
IMAGE_SAFETY The generated image potentially violates safety policies.
IMAGE_PROHIBITED_CONTENT The generated image may contain prohibited content.
IMAGE_RECITATION The generated image may be a recitation from a source.
IMAGE_OTHER The image generation stopped for a reason not otherwise specified.
UNEXPECTED_TOOL_CALL The model generated a function call that is semantically invalid. This can happen, for example, if function calling is not enabled or the generated function is not in the function declaration.
NO_IMAGE The model was expected to generate an image, but didn't.

SafetyRating

A safety rating for a piece of content.

The safety rating contains the harm category and the harm probability level.

Fields
category enum (HarmCategory)

Output only. The harm category of this rating.

probability enum (HarmProbability)

Output only. The probability of harm for this category.

probabilityScore number

Output only. The probability score of harm for this category.

severity enum (HarmSeverity)

Output only. The severity of harm for this category.

severityScore number

Output only. The severity score of harm for this category.

blocked boolean

Output only. Indicates whether the content was blocked because of this rating.

overwrittenThreshold enum (HarmBlockThreshold)

Output only. The overwritten threshold for the safety category of Gemini 2.0 image out. If minors are detected in the output image, the threshold of each safety category will be overwritten if user sets a lower threshold.

JSON representation 
{
  "category": enum (HarmCategory),
  "probability": enum (HarmProbability),
  "probabilityScore": number,
  "severity": enum (HarmSeverity),
  "severityScore": number,
  "blocked": boolean,
  "overwrittenThreshold": enum (HarmBlockThreshold)
}

HarmProbability

The probability of harm for a given category.

Enums
HARM_PROBABILITY_UNSPECIFIED The harm probability is unspecified.
NEGLIGIBLE The harm probability is negligible.
LOW The harm probability is low.
MEDIUM The harm probability is medium.
HIGH The harm probability is high.

HarmSeverity

The severity of harm for a given category.

Enums
HARM_SEVERITY_UNSPECIFIED The harm severity is unspecified.
HARM_SEVERITY_NEGLIGIBLE The harm severity is negligible.
HARM_SEVERITY_LOW The harm severity is low.
HARM_SEVERITY_MEDIUM The harm severity is medium.
HARM_SEVERITY_HIGH The harm severity is high.

CitationMetadata

A collection of citations that apply to a piece of generated content.

Fields
citations[] object (Citation)

Output only. A list of citations for the content.

JSON representation 
{
  "citations": [
    {
      object (Citation)
    }
  ]
}

Citation

A citation for a piece of generatedcontent.

Fields
startIndex integer

Output only. The start index of the citation in the content.

endIndex integer

Output only. The end index of the citation in the content.

uri string

Output only. The URI of the source of the citation.

title string

Output only. The title of the source of the citation.

license string

Output only. The license of the source of the citation.

publicationDate object (Date)

Output only. The publication date of the source of the citation.

JSON representation 
{
  "startIndex": integer,
  "endIndex": integer,
  "uri": string,
  "title": string,
  "license": string,
  "publicationDate": {
    object (Date)
  }
}

GroundingMetadata

Information about the sources that support the content of a response.

When grounding is enabled, the model returns citations for claims in the response. This object contains the retrieved sources.

Fields
webSearchQueries[] string

Optional. The web search queries that were used to generate the content. This field is populated only when the grounding source is Google Search.

groundingChunks[] object (GroundingChunk)

A list of supporting references retrieved from the grounding source. This field is populated when the grounding source is Google Search, Vertex AI Search, or Google Maps.

groundingSupports[] object (GroundingSupport)

Optional. A list of grounding supports that connect the generated content to the grounding chunks. This field is populated when the grounding source is Google Search or Vertex AI Search.

sourceFlaggingUris[] object (SourceFlaggingUri)

Optional. Output only. A list of URIs that can be used to flag a place or review for inappropriate content. This field is populated only when the grounding source is Google Maps.

searchEntryPoint object (SearchEntryPoint)

Optional. A web search entry point that can be used to display search results. This field is populated only when the grounding source is Google Search.

retrievalMetadata object (RetrievalMetadata)

Optional. Output only. metadata related to the retrieval grounding source.

googleMapsWidgetContextToken string

Optional. Output only. A token that can be used to render a Google Maps widget with the contextual data. This field is populated only when the grounding source is Google Maps.

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

SearchEntryPoint

An entry point for displaying Google Search results.

A SearchEntryPoint is populated when the grounding source for a model's response is Google Search. It provides information that you can use to display the search results in your application.

Fields
renderedContent string

Optional. An HTML snippet that can be embedded in a web page or an application's webview. This snippet displays a search result, including the title, URL, and a brief description of the search result.

sdkBlob string (bytes format)

Optional. A base64-encoded JSON object that contains a list of search queries and their corresponding search URLs. This information can be used to build a custom search UI.

A base64-encoded string.

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

GroundingChunk

A piece of evidence that supports a claim made by the model.

This is used to show a citation for a claim made by the model. When grounding is enabled, the model returns a GroundingChunk that contains a reference to the source of the information.

Fields
chunk_type Union type
The source of the grounding chunk, which can be from Google Search, Vertex AI Search, or Google Maps. chunk_type can be only one of the following:
web object (Web)

A grounding chunk from a web page, typically from Google Search. See the Web message for details.

retrievedContext object (RetrievedContext)

A grounding chunk from a data source retrieved by a retrieval tool, such as Vertex AI Search. See the RetrievedContext message for details

maps object (Maps)

A grounding chunk from Google Maps. See the Maps message for details.

JSON representation 
{

  // chunk_type
  "web": {
    object (Web)
  },
  "retrievedContext": {
    object (RetrievedContext)
  },
  "maps": {
    object (Maps)
  }
  // Union type
}

Web

A Web chunk is a piece of evidence that comes from a web page. It contains the URI of the web page, the title of the page, and the domain of the page. This is used to provide the user with a link to the source of the information.

Fields
uri string

The URI of the web page that contains the evidence.

title string

The title of the web page that contains the evidence.

domain string

The domain of the web page that contains the evidence. This can be used to filter out low-quality sources.

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

RetrievedContext

Context retrieved from a data source to ground the model's response. This is used when a retrieval tool fetches information from a user-provided corpus or a public dataset.

Fields
context_details Union type
Provides tool-specific details about the retrieved context. This allows for different types of retrieval tools to return their own specific metadata. context_details can be only one of the following:
ragChunk object (RagChunk)

Additional context for a Retrieval-Augmented Generation (RAG) retrieval result. This is populated only when the RAG retrieval tool is used.

uri string

The URI of the retrieved data source.

title string

The title of the retrieved data source.

text string

The content of the retrieved data source.

documentName string

Output only. The full resource name of the referenced Vertex AI Search document. This is used to identify the specific document that was retrieved. The format is projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}/branches/{branch}/documents/{document}.

JSON representation 
{

  // context_details
  "ragChunk": {
    object (RagChunk)
  }
  // Union type
  "uri": string,
  "title": string,
  "text": string,
  "documentName": string
}

Maps

A Maps chunk is a piece of evidence that comes from Google Maps. It contains information about a place, such as its name, address, and reviews. This is used to provide the user with rich, location-based information.

Fields
placeAnswerSources object (PlaceAnswerSources)

The sources that were used to generate the place answer. This includes review snippets and photos that were used to generate the answer, as well as URIs to flag content.

uri string

The URI of the place.

title string

The title of the place.

text string

The text of the place answer.

placeId string

This Place's resource name, in places/{placeId} format. This can be used to look up the place in the Google Maps API.

JSON representation 
{
  "placeAnswerSources": {
    object (PlaceAnswerSources)
  },
  "uri": string,
  "title": string,
  "text": string,
  "placeId": string
}

PlaceAnswerSources

The sources that were used to generate the place answer. This includes review snippets and photos that were used to generate the answer, as well as URIs to flag content.

Fields
reviewSnippets[] object (ReviewSnippet)

Snippets of reviews that were used to generate the answer.

JSON representation 
{
  "reviewSnippets": [
    {
      object (ReviewSnippet)
    }
  ]
}

ReviewSnippet

A review snippet that is used to generate the answer.

Fields
reviewId string

The id of the review that is being referenced.

googleMapsUri string

A link to show the review on Google Maps.

title string

The title of the review.

JSON representation 
{
  "reviewId": string,
  "googleMapsUri": string,
  "title": string
}

GroundingSupport

A collection of supporting references for a segment of the model's response.

Fields
groundingChunkIndices[] integer

A list of indices into the groundingChunks field of the GroundingMetadata message. These indices specify which grounding chunks support the claim made in the content segment.

For example, if this field has the values [1, 3], it means that groundingChunks[1] and groundingChunks[3] are the sources for the claim in the content segment.

confidenceScores[] number

The confidence scores for the support references. This list is parallel to the groundingChunkIndices list. A score is a value between 0.0 and 1.0, with a higher score indicating a higher confidence that the reference supports the claim.

For Gemini 2.0 and before, this list has the same size as groundingChunkIndices. For Gemini 2.5 and later, this list is empty and should be ignored.

segment object (Segment)

The content segment that this support message applies to.

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

Segment

A segment of the content.

Fields
partIndex integer

Output only. The index of the Part object that this segment belongs to. This is useful for associating the segment with a specific part of the content.

startIndex integer

Output only. The start index of the segment in the Part, measured in bytes. This marks the beginning of the segment and is inclusive, meaning the byte at this index is the first byte of the segment.

endIndex integer

Output only. The end index of the segment in the Part, measured in bytes. This marks the end of the segment and is exclusive, meaning the segment includes content up to, but not including, the byte at this index.

text string

Output only. The text of the segment.

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

RetrievalMetadata

metadata related to the retrieval grounding source. This is part of the GroundingMetadata returned when grounding is enabled.

Fields
googleSearchDynamicRetrievalScore number

Optional. A score indicating how likely it is that a Google Search query could help answer the prompt. The score is in the range of [0, 1]. A score of 1 means the model is confident that a search will be helpful, and 0 means it is not. This score is populated only when Google Search grounding and dynamic retrieval are enabled. The score is used to determine whether to trigger a search.

JSON representation 
{
  "googleSearchDynamicRetrievalScore": number
}

SourceFlaggingUri

A URI that can be used to flag a place or review for inappropriate content. This is populated only when the grounding source is Google Maps.

Fields
sourceId string

The id of the place or review.

flagContentUri string

The URI that can be used to flag the content.

JSON representation 
{
  "sourceId": string,
  "flagContentUri": string
}

UrlContextMetadata

metadata returned when the model uses the urlContext tool to get information from a user-provided URL.

Fields
urlMetadata[] object (UrlMetadata)

Output only. A list of URL metadata, with one entry for each URL retrieved by the tool.

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

UrlMetadata

The metadata for a single URL retrieval.

Fields
retrievedUrl string

The URL retrieved by the tool.

urlRetrievalStatus enum (UrlRetrievalStatus)

The status of the URL retrieval.

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

UrlRetrievalStatus

The status of a URL retrieval.

Enums
URL_RETRIEVAL_STATUS_UNSPECIFIED Default value. This value is unused.
URL_RETRIEVAL_STATUS_SUCCESS The URL was retrieved successfully.
URL_RETRIEVAL_STATUS_ERROR The URL retrieval failed.

PromptFeedback

Content filter results for a prompt sent in the request. Note: This is sent only in the first stream chunk and only if no candidates were generated due to content violations.

Fields
blockReason enum (BlockedReason)

Output only. The reason why the prompt was blocked.

safetyRatings[] object (SafetyRating)

Output only. A list of safety ratings for the prompt. There is one rating per category.

blockReasonMessage string

Output only. A readable message that explains the reason why the prompt was blocked.

JSON representation 
{
  "blockReason": enum (BlockedReason),
  "safetyRatings": [
    {
      object (SafetyRating)
    }
  ],
  "blockReasonMessage": string
}

BlockedReason

The reason why the prompt was blocked.

Enums
BLOCKED_REASON_UNSPECIFIED The blocked reason is unspecified.
SAFETY The prompt was blocked for safety reasons.
OTHER The prompt was blocked for other reasons. For example, it may be due to the prompt's language, or because it contains other harmful content.
BLOCKLIST The prompt was blocked because it contains a term from the terminology blocklist.
PROHIBITED_CONTENT The prompt was blocked because it contains prohibited content.
MODEL_ARMOR The prompt was blocked by Model Armor.
IMAGE_SAFETY The prompt was blocked because it contains content that is unsafe for image generation.
JAILBREAK The prompt was blocked as a jailbreak attempt.

UsageMetadata

Usage metadata about the content generation request and response. This message provides a detailed breakdown of token usage and other relevant metrics.

Fields
promptTokenCount integer

The total number of tokens in the prompt. This includes any text, images, or other media provided in the request. When cachedContent is set, this also includes the number of tokens in the cached content.

candidatesTokenCount integer

The total number of tokens in the generated candidates.

totalTokenCount integer

The total number of tokens for the entire request. This is the sum of promptTokenCount, candidatesTokenCount, toolUsePromptTokenCount, and thoughtsTokenCount.

toolUsePromptTokenCount integer

Output only. The number of tokens in the results from tool executions, which are provided back to the model as input, if applicable.

thoughtsTokenCount integer

Output only. The number of tokens that were part of the model's generated "thoughts" output, if applicable.

cachedContentTokenCount integer

Output only. The number of tokens in the cached content that was used for this request.

promptTokensDetails[] object (ModalityTokenCount)

Output only. A detailed breakdown of the token count for each modality in the prompt.

cacheTokensDetails[] object (ModalityTokenCount)

Output only. A detailed breakdown of the token count for each modality in the cached content.

candidatesTokensDetails[] object (ModalityTokenCount)

Output only. A detailed breakdown of the token count for each modality in the generated candidates.

toolUsePromptTokensDetails[] object (ModalityTokenCount)

Output only. A detailed breakdown by modality of the token counts from the results of tool executions, which are provided back to the model as input.

trafficType enum (TrafficType)

Output only. The traffic type for this request.

JSON representation 
{
  "promptTokenCount": integer,
  "candidatesTokenCount": integer,
  "totalTokenCount": integer,
  "toolUsePromptTokenCount": integer,
  "thoughtsTokenCount": integer,
  "cachedContentTokenCount": integer,
  "promptTokensDetails": [
    {
      object (ModalityTokenCount)
    }
  ],
  "cacheTokensDetails": [
    {
      object (ModalityTokenCount)
    }
  ],
  "candidatesTokensDetails": [
    {
      object (ModalityTokenCount)
    }
  ],
  "toolUsePromptTokensDetails": [
    {
      object (ModalityTokenCount)
    }
  ],
  "trafficType": enum (TrafficType)
}

TrafficType

The type of traffic that this request was processed with, indicating which quota is consumed.

Enums
TRAFFIC_TYPE_UNSPECIFIED Unspecified request traffic type.
ON_DEMAND The request was processed using Pay-As-You-Go quota.
PROVISIONED_THROUGHPUT type for Provisioned Throughput traffic.