openapi: 3.1.0
info:
title: Google Gemini API
description: >-
Google's Gemini API provides access to generative AI models for text
generation, multimodal understanding, and embedding creation. The API
supports text, image, audio, and video inputs with configurable safety
settings, generation parameters, and tool use capabilities.
version: v1beta
termsOfService: https://ai.google.dev/terms
contact:
name: Google AI Developer Support
url: https://ai.google.dev/docs/support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://generativelanguage.googleapis.com/v1beta
description: Google Generative Language API v1beta
tags:
- name: Content Generation
description: >-
Generate content using Gemini models with text, image, audio, and video
inputs. Supports multimodal prompts, function calling, structured output,
and configurable safety settings.
- name: Embeddings
description: >-
Generate text embedding vectors for semantic search, classification,
clustering, and retrieval tasks using Gemini embedding models.
paths:
/models/{model}:generateContent:
post:
operationId: generateContent
tags:
- Content Generation
summary: >-
Google Gemini Generates a model response given an input GenerateContentRequest. Refer to the text generation guide for detailed usage information. Input capabilities differ between models, including tuned models.
description: >-
Generates a response from the model given an input. The input can
include text, images, audio, video, and other multimodal content.
The model processes the input according to its capabilities and returns
generated content along with safety ratings and usage metadata.
parameters:
- name: model
in: path
required: true
description: >-
The name of the Model to use for generating the completion. Format:
models/{model}. Example: models/gemini-2.0-flash.
schema:
type: string
example: gemini-2.0-flash
- name: key
in: query
required: true
description: API key for authentication.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateContentRequest'
responses:
'200':
description: Successful response with generated content.
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateContentResponse'
'400':
description: >-
Bad request. The request body is malformed or missing required
fields.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized. Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: >-
Forbidden. The API key does not have permission to access the
requested model.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found. The specified model does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: >-
Too many requests. Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/models/{model}:streamGenerateContent:
post:
operationId: streamGenerateContent
tags:
- Content Generation
summary: >-
Google Gemini Generates a streamed response from the model given an input GenerateContentRequest. Returns a stream of GenerateContentResponse chunks using server-sent events.
description: >-
Generates a streamed response from the model. This endpoint behaves
identically to generateContent but returns partial responses
incrementally as server-sent events. Each event contains a
GenerateContentResponse with one or more candidate content parts.
Use the alt=sse query parameter to enable streaming.
parameters:
- name: model
in: path
required: true
description: >-
The name of the Model to use for generating the completion. Format:
models/{model}. Example: models/gemini-2.0-flash.
schema:
type: string
example: gemini-2.0-flash
- name: key
in: query
required: true
description: API key for authentication.
schema:
type: string
- name: alt
in: query
required: false
description: Set to 'sse' for server-sent events streaming.
schema:
type: string
enum:
- sse
default: sse
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateContentRequest'
responses:
'200':
description: >-
Successful streaming response. Returns a stream of
GenerateContentResponse objects as server-sent events.
content:
text/event-stream:
schema:
$ref: '#/components/schemas/GenerateContentResponse'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests. Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/models/{model}:embedContent:
post:
operationId: embedContent
tags:
- Embeddings
summary: >-
Google Gemini Generates a text embedding vector from the input Content using the specified Gemini Embedding model.
description: >-
Generates an embedding from the model given input content. The
embedding is a vector representation of the input text that captures
semantic meaning. Embeddings can be used for semantic search, text
classification, clustering, and retrieval tasks. Only the text parts
of the input content are used for embedding generation.
parameters:
- name: model
in: path
required: true
description: >-
The model name to use for embedding. Format: models/{model}.
Example: models/gemini-embedding-001.
schema:
type: string
example: gemini-embedding-001
- name: key
in: query
required: true
description: API key for authentication.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmbedContentRequest'
responses:
'200':
description: Successful response with the generated embedding vector.
content:
application/json:
schema:
$ref: '#/components/schemas/EmbedContentResponse'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized. Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not found. The specified model does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests. Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: key
description: >-
API key for authenticating requests. Obtain from Google AI Studio at
https://aistudio.google.com/app/apikey.
schemas:
GenerateContentRequest:
type: object
description: >-
Request to generate a completion from the model. Contains the
conversation content, optional tools, safety settings, system
instructions, and generation configuration.
required:
- contents
properties:
contents:
type: array
description: >-
Required. The content of the current conversation with the model.
For single-turn queries, this is a single instance. For multi-turn
queries such as chat, this is a repeated field that contains the
conversation history and the latest request.
items:
$ref: '#/components/schemas/Content'
tools:
type: array
description: >-
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.
items:
$ref: '#/components/schemas/Tool'
toolConfig:
$ref: '#/components/schemas/ToolConfig'
safetySettings:
type: array
description: >-
A list of unique SafetySetting instances for blocking unsafe
content. This will be enforced on the
GenerateContentRequest.contents and
GenerateContentResponse.candidates. There should be at most one
setting for each SafetyCategory type.
items:
$ref: '#/components/schemas/SafetySetting'
systemInstruction:
$ref: '#/components/schemas/Content'
generationConfig:
$ref: '#/components/schemas/GenerationConfig'
cachedContent:
type: string
description: >-
The name of the cached content used as context to serve the
prediction. Format: cachedContents/{cachedContent}.
GenerateContentResponse:
type: object
description: >-
Response from the model supporting multiple candidate responses. Safety
ratings and content filtering are reported for both prompt in
GenerateContentResponse.prompt_feedback and for each candidate in
finishReason and safetyRatings.
properties:
candidates:
type: array
description: >-
Candidate responses from the model. There may be multiple
candidates if candidateCount was set in the GenerationConfig.
items:
$ref: '#/components/schemas/Candidate'
promptFeedback:
$ref: '#/components/schemas/PromptFeedback'
usageMetadata:
$ref: '#/components/schemas/UsageMetadata'
modelVersion:
type: string
description: The model version used to generate the response.
responseId:
type: string
description: Unique identifier for the response.
Content:
type: object
description: >-
The base structured datatype containing multi-part content of a
message. A Content includes a role field designating the producer
of the Content and a parts field containing multi-part data that
contains the content of the message turn.
properties:
parts:
type: array
description: >-
Ordered Parts that constitute a single message. Parts may have
different MIME types.
items:
$ref: '#/components/schemas/Part'
role:
type: string
description: >-
The producer of the content. Must be either 'user' or 'model'.
Useful to set for multi-turn conversations, otherwise can be left
blank or unset.
enum:
- user
- model
Part:
type: object
description: >-
A datatype containing media that is part of a multi-part Content
message. A Part consists of data which has an associated datatype.
A Part can only contain one of the accepted types in its
corresponding field.
properties:
text:
type: string
description: Inline text.
inlineData:
$ref: '#/components/schemas/Blob'
fileData:
$ref: '#/components/schemas/FileData'
functionCall:
$ref: '#/components/schemas/FunctionCall'
functionResponse:
$ref: '#/components/schemas/FunctionResponse'
Blob:
type: object
description: Raw media bytes with MIME type information.
properties:
mimeType:
type: string
description: >-
The IANA standard MIME type of the source data. Examples:
image/png, image/jpeg, audio/mp3, video/mp4.
data:
type: string
format: byte
description: Raw bytes for media formats encoded as base64.
FileData:
type: object
description: URI based data for media uploaded via the Files API.
properties:
mimeType:
type: string
description: The IANA standard MIME type of the source data.
fileUri:
type: string
description: URI of the file.
FunctionCall:
type: object
description: >-
A predicted FunctionCall returned from the model that contains a
string representing the FunctionDeclaration.name with the arguments
and their values.
properties:
name:
type: string
description: >-
Required. The name of the function to call. Must be a-z, A-Z,
0-9, or contain underscores and dashes, with a maximum length of
63.
args:
type: object
description: >-
The function parameters and values in JSON object format.
additionalProperties: true
FunctionResponse:
type: object
description: >-
The result output from a FunctionCall that contains a string
representing the FunctionDeclaration.name and a structured JSON object
containing any output from the function call.
properties:
name:
type: string
description: >-
Required. The name of the function to call. Must be a-z, A-Z,
0-9, or contain underscores and dashes, with a maximum length of
63.
response:
type: object
description: >-
Required. The function response in JSON object format.
additionalProperties: true
Tool:
type: object
description: >-
Tool details that the model may use to generate 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.
properties:
functionDeclarations:
type: array
description: >-
A list of FunctionDeclarations available to the model that can
be used for function calling. The model or system does not execute
the function. Instead the defined function may be returned as a
FunctionCall with arguments to the client side for execution.
items:
$ref: '#/components/schemas/FunctionDeclaration'
codeExecution:
type: object
description: >-
Enables the model to execute code as part of generation. Code
execution is enabled by passing an empty object.
FunctionDeclaration:
type: object
description: >-
Structured representation of a function declaration as defined by
the OpenAPI 3.0 specification. Included in this declaration are the
function name and parameters.
required:
- name
properties:
name:
type: string
description: >-
Required. The name of the function. Must be a-z, A-Z, 0-9, or
contain underscores and dashes, with a maximum length of 63.
description:
type: string
description: >-
Required. A brief description of the function.
parameters:
type: object
description: >-
Describes the parameters to this function. Reflects the Open
API 3.03 Parameter Object. String key: the name of the parameter.
Parameter names are case sensitive. Schema Value: the Schema
defining the type used for the parameter.
additionalProperties: true
ToolConfig:
type: object
description: >-
The Tool configuration containing parameters for specifying Tool
use in the request.
properties:
functionCallingConfig:
$ref: '#/components/schemas/FunctionCallingConfig'
FunctionCallingConfig:
type: object
description: Configuration for specifying function calling behavior.
properties:
mode:
type: string
description: >-
Specifies the mode in which function calling should execute.
enum:
- MODE_UNSPECIFIED
- AUTO
- ANY
- NONE
allowedFunctionNames:
type: array
description: >-
A set of function names that, when provided, limits the functions
the model will call. This should only be set when the Mode is
ANY. Function names should match FunctionDeclaration.name.
items:
type: string
SafetySetting:
type: object
description: >-
Safety setting, affecting the safety-blocking behavior. Passing a
safety setting for a category changes the allowed probability that
content is blocked.
properties:
category:
type: string
description: Required. The category for this setting.
enum:
- HARM_CATEGORY_UNSPECIFIED
- HARM_CATEGORY_HATE_SPEECH
- HARM_CATEGORY_SEXUALLY_EXPLICIT
- HARM_CATEGORY_DANGEROUS_CONTENT
- HARM_CATEGORY_HARASSMENT
- HARM_CATEGORY_CIVIC_INTEGRITY
threshold:
type: string
description: Required. Controls the probability threshold at which harm is blocked.
enum:
- HARM_BLOCK_THRESHOLD_UNSPECIFIED
- BLOCK_LOW_AND_ABOVE
- BLOCK_MEDIUM_AND_ABOVE
- BLOCK_ONLY_HIGH
- BLOCK_NONE
- OFF
GenerationConfig:
type: object
description: >-
Configuration options for model generation and outputs. Not all
parameters are configurable for every model.
properties:
candidateCount:
type: integer
format: int32
description: >-
Number of generated responses to return. Currently, this value
can only be set to 1. If unset, this will default to 1.
stopSequences:
type: array
description: >-
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.
items:
type: string
maxOutputTokens:
type: integer
format: int32
description: >-
The maximum number of tokens to include in a response candidate.
Note: The default value varies by model.
temperature:
type: number
format: float
description: >-
Controls the randomness of the output. Values can range from
0.0 to 2.0 inclusive. A higher value will produce responses that
are more varied and creative, while a value closer to 0.0 will
typically result in more straightforward responses from the model.
topP:
type: number
format: float
description: >-
The maximum cumulative probability of tokens to consider when
sampling. The model uses combined Top-k and Top-p (nucleus)
sampling. Tokens are sorted based on their assigned probabilities
so that only the most likely tokens are considered.
topK:
type: integer
format: int32
description: >-
The maximum number of tokens to consider when sampling. Gemini
models use Top-p (nucleus) sampling or a combination of Top-k
and nucleus sampling.
responseMimeType:
type: string
description: >-
MIME type of the generated candidate text. Supported MIME types
are text/plain (default), application/json (JSON response in the
response candidates), and text/x.enum (for classification tasks).
responseSchema:
type: object
description: >-
Output schema of the generated candidate text. Schemas must be
a subset of the OpenAPI schema and can be objects, primitives,
or arrays. If set, a compatible responseMimeType must also be
set. Compatible MIME types: application/json.
additionalProperties: true
presencePenalty:
type: number
format: float
description: >-
Positive values penalize tokens that have already appeared in
the generated text, increasing the likelihood of generating more
diverse content.
frequencyPenalty:
type: number
format: float
description: >-
Positive values penalize tokens based on their frequency in the
generated text, decreasing the likelihood of repeating the same
content verbatim.
seed:
type: integer
format: int32
description: >-
Seed used in decoding. If specified with the same seed and
parameters, the model will attempt to return the same response.
Candidate:
type: object
description: >-
A response candidate generated from the model.
properties:
content:
$ref: '#/components/schemas/Content'
finishReason:
type: string
description: >-
The reason why the model stopped generating tokens. If empty,
the model has not stopped generating tokens.
enum:
- FINISH_REASON_UNSPECIFIED
- STOP
- MAX_TOKENS
- SAFETY
- RECITATION
- LANGUAGE
- OTHER
- BLOCKLIST
- PROHIBITED_CONTENT
- SPII
- MALFORMED_FUNCTION_CALL
safetyRatings:
type: array
description: >-
List of ratings for the safety of a response candidate. There
is at most one rating per category.
items:
$ref: '#/components/schemas/SafetyRating'
citationMetadata:
$ref: '#/components/schemas/CitationMetadata'
tokenCount:
type: integer
format: int32
description: Token count for this candidate.
index:
type: integer
format: int32
description: Index of the candidate in the list of response candidates.
SafetyRating:
type: object
description: >-
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.
properties:
category:
type: string
description: The category for this rating.
enum:
- HARM_CATEGORY_UNSPECIFIED
- HARM_CATEGORY_HATE_SPEECH
- HARM_CATEGORY_SEXUALLY_EXPLICIT
- HARM_CATEGORY_DANGEROUS_CONTENT
- HARM_CATEGORY_HARASSMENT
- HARM_CATEGORY_CIVIC_INTEGRITY
probability:
type: string
description: The probability of harm for this content.
enum:
- HARM_PROBABILITY_UNSPECIFIED
- NEGLIGIBLE
- LOW
- MEDIUM
- HIGH
blocked:
type: boolean
description: Was this content blocked because of this rating?
CitationMetadata:
type: object
description: >-
A collection of source attributions for a piece of content.
properties:
citationSources:
type: array
description: Citations to sources for a specific response.
items:
$ref: '#/components/schemas/CitationSource'
CitationSource:
type: object
description: >-
A citation to a source for a portion of a specific response.
properties:
startIndex:
type: integer
format: int32
description: Start of segment of the response that is attributed to this source.
endIndex:
type: integer
format: int32
description: End of the attributed segment, exclusive.
uri:
type: string
description: URI that is attributed as a source for a portion of the text.
license:
type: string
description: License for the GitHub project that is attributed as a source.
PromptFeedback:
type: object
description: >-
A set of the feedback metadata for the prompt specified in
GenerateContentRequest.content.
properties:
blockReason:
type: string
description: If set, the prompt was blocked and no candidates are returned.
enum:
- BLOCK_REASON_UNSPECIFIED
- SAFETY
- OTHER
- BLOCKLIST
- PROHIBITED_CONTENT
safetyRatings:
type: array
description: Ratings for safety of the prompt.
items:
$ref: '#/components/schemas/SafetyRating'
UsageMetadata:
type: object
description: Metadata on the generation request's token usage.
properties:
promptTokenCount:
type: integer
format: int32
description: Number of tokens in the prompt.
candidatesTokenCount:
type: integer
format: int32
description: Total number of tokens across all the generated response candidates.
totalTokenCount:
type: integer
format: int32
description: >-
Total token count for the generation request (prompt +
response candidates).
cachedContentTokenCount:
type: integer
format: int32
description: Number of tokens in the cached part of the prompt (the cached content).
EmbedContentRequest:
type: object
description: >-
Request containing the Content for the model to embed.
required:
- content
properties:
content:
$ref: '#/components/schemas/Content'
taskType:
type: string
description: >-
The type of task for which the embedding will be used. Not
supported by older embedding models.
enum:
- TASK_TYPE_UNSPECIFIED
- RETRIEVAL_QUERY
- RETRIEVAL_DOCUMENT
- SEMANTIC_SIMILARITY
- CLASSIFICATION
- CLUSTERING
- QUESTION_ANSWERING
- FACT_VERIFICATION
- CODE_RETRIEVAL_QUERY
title:
type: string
description: >-
An optional title for the text. Only applicable when TaskType
is RETRIEVAL_DOCUMENT. Note: Specifying a title for
RETRIEVAL_DOCUMENT provides better quality embeddings for
retrieval.
outputDimensionality:
type: integer
format: int32
description: >-
Reduced dimension for the output embedding. If set, excessive
values in the output embedding are truncated from the end.
Supported by newer models since 2024 only.
EmbedContentResponse:
type: object
description: The response to an EmbedContentRequest.
properties:
embedding:
$ref: '#/components/schemas/ContentEmbedding'
ContentEmbedding:
type: object
description: >-
A list of floats representing an embedding.
properties:
values:
type: array
description: The embedding values.
items:
type: number
format: float
ErrorResponse:
type: object
description: Error response from the API.
properties:
error:
type: object
properties:
code:
type: integer
description: HTTP error code.
message:
type: string
description: Human-readable error message.
status:
type: string
description: Error status string.
security:
- ApiKeyAuth: []