Gemini API Reference

Generate Content

Endpoint

POST https://api.rockapi.ru/google-ai-studio/v1beta/{model=models/*}:generateContent

Path Parameters

Name	Type	Description
model	string	Required. The name of the Model to use for generating the completion. Format: name=models/{model}.

Request Body

The request body contains data with the following structure:

Fields

Name	Type	Description
contents[]	object	Required. The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries, this is a repeated field that contains conversation history + latest request.
tools[]	object	Optional. A list of Tools the model may use to generate the next response. A Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model. The only supported tool is currently Function.
toolConfig	object	Optional. Tool configuration for any Tool specified in the request.
safetySettings[]	object	Optional. A list of unique SafetySetting instances for blocking unsafe content. This will be enforced on the GenerateContentRequest.contents and GenerateContentResponse.candidates. There should not be more than one setting for each SafetyCategory type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each SafetyCategory specified in the safetySettings. If there is no SafetySetting for a given SafetyCategory provided in the list, the API will use the default safety setting for that category. Supported harm categories: HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT.
systemInstruction	object	Optional. Developer set system instruction. Currently, text only.
generationConfig	object	Optional. Configuration options for model generation and outputs.
cachedContent	string	Optional. The name of the cached content used as context to serve the prediction. Note: only used in explicit caching, where users can have control over caching (e.g., what content to cache) and enjoy guaranteed cost savings. Format: cachedContents/{cachedContent}.

Example Request

import google.generativeai as genai
from google.api_core.client_options import ClientOptions

genai.configure(
    api_key='$ROCKAPI_API_KEY',
    transport='rest',
    client_options=ClientOptions(api_endpoint='https://api.rockapi.ru/google-ai-studio')
)

model = genai.GenerativeModel("gemini-1.5-flash")
response = model.generate_content("Write a story about a magic backpack.")
print(response.text)

Response Body

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

---

Stream Generate Content

Endpoint

POST https://api.rockapi.ru/google-ai-studio/v1beta/{model=models/*}:streamGenerateContent

Path Parameters

Name	Type	Description
model	string	Required. The name of the Model to use for generating the completion. Format: name=models/{model}.

Request Body

The request body contains data with the following structure:

Fields

Name	Type	Description
contents[]	object	Required. The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries, this is a repeated field that contains conversation history + latest request.
tools[]	object	Optional. A list of Tools the model may use to generate the next response. A Tool is a piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model. The only supported tool is currently Function.
toolConfig	object	Optional. Tool configuration for any Tool specified in the request.
safetySettings[]	object	Optional. A list of unique SafetySetting instances for blocking unsafe content. This will be enforced on the GenerateContentRequest.contents and GenerateContentResponse.candidates. There should not be more than one setting for each SafetyCategory type. The API will block any contents and responses that fail to meet the thresholds set by these settings. This list overrides the default settings for each SafetyCategory specified in the safetySettings. If there is no SafetySetting for a given SafetyCategory provided in the list, the API will use the default safety setting for that category. Supported harm categories: HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT.
systemInstruction	object	Optional. Developer set system instruction. Currently, text only.
generationConfig	object	Optional. Configuration options for model generation and outputs.
cachedContent	string	Optional. The name of the cached content used as context to serve the prediction. Note: only used in explicit caching, where users can have control over caching (e.g., what content to cache) and enjoy guaranteed cost savings. Format: cachedContents/{cachedContent}.

Example Request

import google.generativeai as genai
from google.api_core.client_options import ClientOptions

genai.configure(
    api_key='$ROCKAPI_API_KEY',
    transport='rest',
    client_options=ClientOptions(api_endpoint='https://api.rockapi.ru/google-ai-studio')
)

model = genai.GenerativeModel("gemini-1.5-flash")
response = model.generate_content("Write a story about a magic backpack.", stream=True)
for chunk in response:
    print(chunk.text)
    print("_" * 80)

Response Body

If successful, the response body contains a stream of GenerateContentResponse instances.

---

GenerateContentResponse

Response from the model supporting multiple candidates.

JSON Representation

Note on safety ratings and content filtering. They are reported for both prompt in GenerateContentResponse.prompt_feedback and for each candidate in finishReason and in safetyRatings. The API contract is that: - either all requested candidates are returned or no candidates at all - no candidates are returned only if there was something wrong with the prompt (see promptFeedback) - feedback on each candidate is reported on finishReason and safetyRatings.

{
  "candidates": [
    {
      object (Candidate)
    }
  ],
  "promptFeedback": {
    object (PromptFeedback)
  },
  "usageMetadata": {
    object (UsageMetadata)
  }
}

Fields

Name	Type	Description
candidates[]	object	Candidate responses from the model.
promptFeedback	object	Returns the prompt's feedback related to the content filters.
usageMetadata	object	Metadata on the generation requests' token usage.

---

PromptFeedback

A set of the feedback metadata the prompt specified in GenerateContentRequest.content.

JSON Representation

{
  "blockReason": "enum (BlockReason)",
  "safetyRatings": [
    {
      "object": "SafetyRating"
    }
  ]
}

Fields

Name	Type	Description
blockReason	enum	Optional. If set, the prompt was blocked and no candidates are returned. Rephrase your prompt.
safetyRatings[]	object	Ratings for safety of the prompt. There is at most one rating per category.

---

BlockReason

Specifies what was the reason why the prompt was blocked.

Enums

Name	Description
BLOCK_REASON_UNSPECIFIED	Default value. This value is unused.
SAFETY	Prompt was blocked due to safety reasons. You can inspect safetyRatings to understand which safety category blocked it.
OTHER	Prompt was blocked due to unknown reasons.

---

UsageMetadata

Metadata on the generation request's token usage.

JSON Representation

{
  "promptTokenCount": "integer",
  "cachedContentTokenCount": "integer",
  "candidatesTokenCount": "integer",
  "totalTokenCount": "integer"
}

Fields

Name	Type	Description
promptTokenCount	integer	Number of tokens in the prompt. When cachedContent is set, this is still the total effective prompt size. I.e., this includes the number of tokens in the cached content.
cachedContentTokenCount	integer	Number of tokens in the cached part of the prompt, i.e., in the cached content.
candidatesTokenCount	integer	Total number of tokens across the generated candidates.
totalTokenCount	integer	Total token count for the generation request (prompt + candidates).

---

Candidate

A response candidate generated from the model.

JSON Representation

{
  "content": {
    "object": "Content"
  },
  "finishReason": "enum (FinishReason)",
  "safetyRatings": [
    {
      "object": "SafetyRating"
    }
  ],
  "citationMetadata": {
    "object": "CitationMetadata"
  },
  "tokenCount": "integer",
  "groundingAttributions": [
    {
      "object": "GroundingAttribution"
    }
  ],
  "index": "integer"
}

Fields

Name	Type	Description
content	object	Generated content returned from the model.
finishReason	enum	Optional. The reason why the model stopped generating tokens.
safetyRatings[]	object	List of ratings for the safety of a response candidate. There is at most one rating per category.
citationMetadata	object	Citation information for model-generated candidate.
tokenCount	integer	Token count for this candidate.
groundingAttributions[]	object	Attribution information for sources that contributed to a grounded answer.
index	integer	Index of the candidate in the list of candidates.

---

FinishReason

Defines the reason why the model stopped generating tokens.

Enums

Name	Description
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 candidate content was flagged for safety reasons.
RECITATION	The candidate content was flagged for recitation reasons.
LANGUAGE	The candidate content was flagged for using an unsupported language.
OTHER	Unknown reason.

---

GroundingAttribution

Attribution for a source that contributed to an answer.

JSON Representation

{
  "sourceId": {
    "object": "AttributionSourceId"
  },
  "content": {
    "object": "Content"
  }
}

Fields

Name	Type	Description
sourceId	object	Identifier for the source contributing to this attribution.
content	object	Grounding source content that makes up this attribution.

---

AttributionSourceId

Identifier for the source contributing to this attribution.

JSON Representation

{
  "groundingPassage": {
    "object": "GroundingPassageId"
  },
  "semanticRetrieverChunk": {
    "object": "SemanticRetrieverChunk"
  }
}

Fields

Name	Type	Description
groundingPassage	object	Identifier for an inline passage.
semanticRetrieverChunk	object	Identifier for a Chunk fetched via Semantic Retriever.

---

GroundingPassageId

Identifier for a part within a GroundingPassage.

JSON Representation

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

Fields

Name	Type	Description
passageId	string	ID of the passage matching the GenerateAnswerRequest's GroundingPassage.id.
partIndex	integer	Index of the part within the GenerateAnswerRequest's GroundingPassage.content.

---

SemanticRetrieverChunk

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

JSON Representation

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

Fields

Name	Type	Description
source	string	Name of the source matching the request's SemanticRetrieverConfig.source. Example: corpora/123 or corpora/123/documents/abc.
chunk	string	Name of the Chunk containing the attributed text. Example: corpora/123/documents/abc/chunks/xyz.

---

CitationMetadata

A collection of source attributions for a piece of content.

JSON Representation

{
  "citationSources": [
    {
      "object": "CitationSource"
    }
  ]
}

Fields

Name	Type	Description
citationSources[]	object	Citations to sources for a specific response.

---

CitationSource

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

JSON Representation

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

Fields

Name	Type	Description
startIndex	integer	Optional. Start of the 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 the segment. License info is required for code citations.

---

GenerationConfig

Configuration options for model generation and outputs. Not all parameters may be configurable for every model.

JSON Representation

{
  "stopSequences": [
    "string"
  ],
  "responseMimeType": "string",
  "responseSchema": {
    "object": "Schema"
  },
  "candidateCount": "integer",
  "maxOutputTokens": "integer",
  "temperature": "number",
  "topP": "number",
  "topK": "integer"
}

Fields

Name	Type	Description
stopSequences[]	string	Optional. The set of character sequences (up to 5) that will stop output generation. If specified, the API will stop at the first appearance of a stop sequence. The stop sequence will not be included as part of the response.
responseMimeType	string	Optional. Output response MIME type of the generated candidate text. Supported MIME types: text/plain (default), application/json (JSON response in the candidates).
responseSchema	object	Optional. Output response schema of the generated candidate text when response MIME type can have schema. Schema can be objects, primitives, or arrays and is a subset of OpenAPI schema. If set, a compatible responseMimeType must also be set. Compatible MIME types: application/json (Schema for JSON response).
candidateCount	integer	Optional. Number of generated responses to return. Currently, this value can only be set to 1. If unset, this will default to 1.
maxOutputTokens	integer	Optional. The maximum number of tokens to include in a candidate. Note: The default value varies by model, see the Model.output_token_limit attribute of the Model returned from the getModel function.
temperature	number	Optional. Controls the randomness of the output. Note: The default value varies by model, see the Model.temperature attribute of the Model returned from the getModel function. Values can range from [0.0, 2.0].
topP	number	Optional. The maximum cumulative probability of tokens to consider when sampling. The model uses combined Top-k and nucleus sampling. Tokens are sorted based on their assigned probabilities so that only the most likely tokens are considered. Top-k sampling directly limits the maximum number of tokens to consider, while Nucleus sampling limits the number of tokens based on the cumulative probability. Note: The default value varies by model, see the Model.top_p attribute of the Model returned from the getModel function.
topK	integer	Optional. The maximum number of tokens to consider when sampling. Models use nucleus sampling or combined Top-k and nucleus sampling. Top-k sampling considers the set of topK most probable tokens. Models running with nucleus sampling don't allow topK setting. Note: The default value varies by model, see the Model.top_k attribute of the Model returned from the getModel function. An empty topK field in Model indicates the model doesn't apply top-k sampling and doesn't allow setting topK on requests.

---

HarmCategory

The category of a rating. These categories cover various kinds of harms that developers may wish to adjust.

Enums

Name	Description
HARM_CATEGORY_UNSPECIFIED	Category is unspecified.
HARM_CATEGORY_DEROGATORY	Negative or harmful comments targeting identity and/or protected attribute.
HARM_CATEGORY_TOXICITY	Content that is rude, disrespectful, or profane.
HARM_CATEGORY_VIOLENCE	Describes scenarios depicting violence against an individual or group, or general descriptions of gore.
HARM_CATEGORY_SEXUAL	Contains references to sexual acts or other lewd content.
HARM_CATEGORY_MEDICAL	Promotes unchecked medical advice.
HARM_CATEGORY_DANGEROUS	Dangerous content that promotes, facilitates, or encourages harmful acts.
HARM_CATEGORY_HARASSMENT	Harassment content.
HARM_CATEGORY_HATE_SPEECH	Hate speech and content.
HARM_CATEGORY_SEXUALLY_EXPLICIT	Sexually explicit content.
HARM_CATEGORY_DANGEROUS_CONTENT	Dangerous content.

---

SafetyRating

Safety rating for a piece of content. The safety rating contains the category of harm and the harm probability level in that category for a piece of content. Content is classified

for safety across a number of harm categories and the probability of the harm classification is included here.

JSON Representation

{
  "category": "enum (HarmCategory)",
  "probability": "enum (HarmProbability)",
  "blocked": "boolean"
}

Fields

Name	Type	Description
category	enum	Required. The category for this rating.
probability	enum	Required. The probability of harm for this content.
blocked	boolean	Was this content blocked because of this rating?

---

HarmProbability

The probability that a piece of content is harmful. The classification system gives the probability of the content being unsafe. This does not indicate the severity of harm for a piece of content.

Enums

Name	Description
HARM_PROBABILITY_UNSPECIFIED	Probability is unspecified.
NEGLIGIBLE	Content has a negligible chance of being unsafe.
LOW	Content has a low chance of being unsafe.
MEDIUM	Content has a medium chance of being unsafe.
HIGH	Content has a high chance of being unsafe.

---

SafetySetting

Safety setting, affecting the safety-blocking behavior. Passing a safety setting for a category changes the allowed probability that content is blocked.

JSON Representation

{
  "category": "enum (HarmCategory)",
  "threshold": "enum (HarmBlockThreshold)"
}

Fields

Name	Type	Description
category	enum	Required. The category for this setting.
threshold	enum	Required. Controls the probability threshold at which harm is blocked.

---

HarmBlockThreshold

Block at and beyond a specified harm probability.

Enums

Name	Description
HARM_BLOCK_THRESHOLD_UNSPECIFIED	Threshold is unspecified.
BLOCK_LOW_AND_ABOVE	Content with NEGLIGIBLE will be allowed.
BLOCK_MEDIUM_AND_ABOVE	Content with NEGLIGIBLE and LOW will be allowed.
BLOCK_ONLY_HIGH	Content with NEGLIGIBLE, LOW, and MEDIUM will be allowed.
BLOCK_NONE	All content will be allowed.