Generative Language API v1beta3 Documentation

The Gemini API allows developers to build generative AI applications using Gemini models. Gemini is our most capable model, built from the ground up to be multimodal. It can generalize and seamlessly understand, operate across, and combine different types of information including language, images, audio, video, and code. You can use the Gemini API for use cases like reasoning across text and images, content generation, dialogue agents, summarization and classification systems, and more.

API Root URL: https://generativelanguage.googleapis.com/

Authentication

To use the Generative Language API, you must provide authentication credentials with each request. The most common way to do this is by using an API key.

API Key

You can obtain an API key from your Google Cloud project. Include this key in your requests as a query parameter named key.

Example: ?key=[YOUR_API_KEY]

Resources

The API is organized into several resources, each with a set of methods to interact with them.

Models Resource

The models resource represents the foundational generative models provided by the API. You can use these methods to list available models, get details about specific models, and use them for generation, embedding, and token counting tasks.

Method: `generativelanguage.models.generateMessage`

Generates a response from the model given an input MessagePrompt. This method is suitable for building conversational applications.

Endpoint: POST /v1beta3/{+model}:generateMessage
Description: Generates a response from the model given an input MessagePrompt.

Parameters

Name	Location	Type	Required	Description
`model`	path	string	Yes	Required. The name of the model to use. Format: `name=models/{model}`.

Request Body

The request body must be a JSON object with the following structure (GenerateMessageRequest):

Field	Type	Required	Description
`prompt`	`MessagePrompt`	Yes	Required. The structured textual input given to the model as a prompt.
`temperature`	number	No	Optional. Controls the randomness of the output. Values can range over `[0.0,1.0]`.
`candidateCount`	integer	No	Optional. The number of generated response messages to return. Must be between `[1, 8]`. Defaults to `1`.
`topP`	number	No	Optional. The maximum cumulative probability of tokens to consider when sampling.
`topK`	integer	No	Optional. The maximum number of tokens to consider when sampling.

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": {
         "messages": [
           {
             "author": "user",
             "content": "Explain the importance of bees to the ecosystem."
           }
         ]
       },
       "temperature": 0.7,
       "candidateCount": 1
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/models/gemini-1.5-flash-001:generateMessage?key=[YOUR_API_KEY]"

Method: `generativelanguage.models.countMessageTokens`

Runs a model's tokenizer on a string and returns the token count. This is useful for understanding how much of a model's context window a prompt will consume.

Endpoint: POST /v1beta3/{+model}:countMessageTokens
Description: Runs a model's tokenizer on a string and returns the token count.

Parameters

Name	Location	Type	Required	Description
`model`	path	string	Yes	Required. The model's resource name. This serves as an ID for the Model to use. Format: `models/{model}`

Request Body

The request body must be a JSON object with the following structure (CountMessageTokensRequest):

Field	Type	Required	Description
`prompt`	`MessagePrompt`	Yes	Required. The prompt, whose token count is to be returned.

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": {
         "messages": [
           {
             "author": "user",
             "content": "How many tokens are in this sentence?"
           }
         ]
       }
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/models/gemini-1.5-flash-001:countMessageTokens?key=[YOUR_API_KEY]"

Method: `generativelanguage.models.get`

Gets information about a specific Model such as its version number, token limits, and other metadata.

Endpoint: GET /v1beta3/{+name}
Description: Gets information about a specific Model.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	Required. The resource name of the model. This name should match a model name returned by the `ListModels` method. Format: `models/{model}`

curl Example

curl "https://generativelanguage.googleapis.com/v1beta3/models/gemini-1.5-flash-001?key=[YOUR_API_KEY]"

Method: `generativelanguage.models.list`

Lists the Models available through the Gemini API.

Endpoint: GET /v1beta3/models
Description: Lists the Models available through the Gemini API.

Parameters

Name	Location	Type	Required	Description
`pageSize`	query	integer	No	The maximum number of `Models` to return (per page). If unspecified, 50 models will be returned per page.
`pageToken`	query	string	No	A page token, received from a previous `ListModels` call.

curl Example

curl "https://generativelanguage.googleapis.com/v1beta3/models?pageSize=10&key=[YOUR_API_KEY]"

Method: `generativelanguage.models.generateText`

Generates a response from the model given an input message. This method is suitable for simple text completion tasks.

Endpoint: POST /v1beta3/{+model}:generateText
Description: Generates a response from the model given an input message.

Parameters

Name	Location	Type	Required	Description
`model`	path	string	Yes	Required. The name of the `Model` or `TunedModel` to use for generating the completion. Example: `models/text-bison-001`.

Request Body

The request body must be a JSON object with the following structure (GenerateTextRequest):

Field	Type	Required	Description
`prompt`	`TextPrompt`	Yes	Required. The free-form input text given to the model as a prompt.
`temperature`	number	No	Optional. Controls the randomness of the output.
`candidateCount`	integer	No	Optional. Number of generated responses to return. Must be between.
`maxOutputTokens`	integer	No	Optional. The maximum number of tokens to include in a candidate.
`topP`	number	No	Optional. The maximum cumulative probability of tokens to consider when sampling.
`topK`	integer	No	Optional. The maximum number of tokens to consider when sampling.

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": {
         "text": "Write a tagline for a coffee shop."
       },
       "temperature": 0.8,
       "candidateCount": 3
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/models/text-bison-001:generateText?key=[YOUR_API_KEY]"

Method: `generativelanguage.models.embedText`

Generates an embedding from the model given an input message. Embeddings are numerical representations of text that can be used for tasks like semantic search or clustering.

Endpoint: POST /v1beta3/{+model}:embedText
Description: Generates an embedding from the model given an input message.

Parameters

Name	Location	Type	Required	Description
`model`	path	string	Yes	Required. The model name to use with the format `model=models/{model}`.

Request Body

The request body must be a JSON object with the following structure (EmbedTextRequest):

Field	Type	Required	Description
`text`	string	Yes	Required. The free-form input text that the model will turn into an embedding.

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "text": "This is the text to be embedded."
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/models/embedding-gecko-001:embedText?key=[YOUR_API_KEY]"

Method: `generativelanguage.models.batchEmbedText`

Generates multiple embeddings from the model given input text in a synchronous call. This is more efficient than making multiple separate embedText requests.

Endpoint: POST /v1beta3/{+model}:batchEmbedText
Description: Generates multiple embeddings from the model given input text in a synchronous call.

Parameters

Name	Location	Type	Required	Description
`model`	path	string	Yes	Required. The name of the `Model` to use for generating the embedding. Example: `models/embedding-gecko-001`.

Request Body

The request body must be a JSON object with the following structure (BatchEmbedTextRequest):

Field	Type	Required	Description
`texts`	array of strings	Yes	Required. The free-form input texts that the model will turn into an embedding. The current limit is 100 texts.

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "texts": [
         "This is the first text.",
         "This is the second text."
       ]
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/models/embedding-gecko-001:batchEmbedText?key=[YOUR_API_KEY]"

Method: `generativelanguage.models.countTextTokens`

Runs a model's tokenizer on a text and returns the token count.

Endpoint: POST /v1beta3/{+model}:countTextTokens
Description: Runs a model's tokenizer on a text and returns the token count.

Parameters

Name	Location	Type	Required	Description
`model`	path	string	Yes	Required. The model's resource name. This serves as an ID for the Model to use. Format: `models/{model}`

Request Body

The request body must be a JSON object with the following structure (CountTextTokensRequest):

Field	Type	Required	Description
`prompt`	`TextPrompt`	Yes	Required. The free-form input text given to the model as a prompt.

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": {
         "text": "Count the tokens in this sentence."
       }
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/models/text-bison-001:countTextTokens?key=[YOUR_API_KEY]"

Tuned Models Resource

The tunedModels resource allows you to create, manage, and use your own fine-tuned versions of the base models. Fine-tuning adapts a model to a specific task or dataset, often resulting in better performance for that use case.

Method: `generativelanguage.tunedModels.get`

Gets information about a specific TunedModel.

Endpoint: GET /v1beta3/{+name}
Description: Gets information about a specific TunedModel.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	Required. The resource name of the model. Format: `tunedModels/my-model-id`

curl Example

curl "https://generativelanguage.googleapis.com/v1beta3/tunedModels/my-tuned-model-id?key=[YOUR_API_KEY]"

Method: `generativelanguage.tunedModels.list`

Lists created tuned models.

Endpoint: GET /v1beta3/tunedModels
Description: Lists created tuned models.

Parameters

Name	Location	Type	Required	Description
`pageSize`	query	integer	No	Optional. The maximum number of `TunedModels` to return (per page).
`pageToken`	query	string	No	Optional. A page token, received from a previous `ListTunedModels` call.
`filter`	query	string	No	Optional. A filter to apply to the list. Examples: "owner:me", "readers:everyone".

curl Example

curl "https://generativelanguage.googleapis.com/v1beta3/tunedModels?pageSize=10&filter=owner:me&key=[YOUR_API_KEY]"

Method: `generativelanguage.tunedModels.create`

Creates a tuned model. This is a long-running operation.

Endpoint: POST /v1beta3/tunedModels
Description: Creates a tuned model.

Parameters

Name	Location	Type	Required	Description
`tunedModelId`	query	string	No	Optional. The unique id for the tuned model if specified. This value should be up to 40 characters and match the regex `[a-z]([a-z0-9-]{0,38}[a-z0-9])?`.

Request Body

The request body must be a JSON object representing the TunedModel to create.

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "displayName": "My Custom Translator",
       "description": "A model fine-tuned for English to French translation.",
       "baseModel": "models/gemini-1.5-flash-001",
       "tuningTask": {
         "trainingData": {
           "examples": {
             "examples": [
               { "textInput": "Hello", "output": "Bonjour" },
               { "textInput": "Goodbye", "output": "Au revoir" }
             ]
           }
         },
         "hyperparameters": {
           "epochCount": 5
         }
       }
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/tunedModels?key=[YOUR_API_KEY]"

Method: `generativelanguage.tunedModels.patch`

Updates a tuned model.

Endpoint: PATCH /v1beta3/{+name}
Description: Updates a tuned model.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	The tuned model name. Example: `tunedModels/sentence-translator-u3b7m`.
`updateMask`	query	string	No	Optional. The list of fields to update, e.g., `displayName,description`.

Request Body

The request body must be a JSON object with the fields to update.

curl Example

curl -X PATCH \
     -H "Content-Type: application/json" \
     -d '{
       "description": "An updated description for my custom translator."
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/tunedModels/sentence-translator-u3b7m?updateMask=description&key=[YOUR_API_KEY]"

Method: `generativelanguage.tunedModels.delete`

Deletes a tuned model.

Endpoint: DELETE /v1beta3/{+name}
Description: Deletes a tuned model.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	Required. The resource name of the model. Format: `tunedModels/my-model-id`.

curl Example

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta3/tunedModels/my-model-to-delete?key=[YOUR_API_KEY]"

Method: `generativelanguage.tunedModels.transferOwnership`

Transfers ownership of the tuned model.

Endpoint: POST /v1beta3/{+name}:transferOwnership
Description: Transfers ownership of the tuned model.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	Required. The resource name of the tuned model to transfer ownership.

Request Body

The request body must be a JSON object with the following structure (TransferOwnershipRequest):

Field	Type	Required	Description
`emailAddress`	string	Yes	Required. The email address of the user to whom the tuned model is being transferred to.

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "emailAddress": "[email protected]"
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/tunedModels/my-tuned-model:transferOwnership?key=[YOUR_API_KEY]"

Method: `generativelanguage.tunedModels.generateText`

Generates a response from a tuned model given an input message.

Endpoint: POST /v1beta3/{+model}:generateText
Description: Generates a response from the model given an input message.

Parameters

Name	Location	Type	Required	Description
`model`	path	string	Yes	Required. The name of the `TunedModel` to use for generating the completion.

Request Body

The request body is identical to the generateText method for base models.

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": {
         "text": "Hello"
       },
       "temperature": 0.2,
       "candidateCount": 1
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/tunedModels/my-custom-translator:generateText?key=[YOUR_API_KEY]"

Tuned Models Permissions Resource

This nested resource manages access control for your tuned models.

Method: `generativelanguage.tunedModels.permissions.create`

Creates a permission to a specific tuned model.

Endpoint: POST /v1beta3/{+parent}/permissions
Description: Create a permission to a specific resource.

Parameters

Name	Location	Type	Required	Description
`parent`	path	string	Yes	Required. The parent resource of the `Permission`. Format: `tunedModels/{tuned_model}`.

Request Body

The request body is a Permission object.

Field	Type	Required	Description
`granteeType`	string	Yes	Type of grantee (`USER`, `GROUP`, `EVERYONE`).
`emailAddress`	string	No	Email for `USER` or `GROUP` grantee types.
`role`	string	Yes	Role to grant (`READER`, `WRITER`, `OWNER`).

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "granteeType": "USER",
       "emailAddress": "[email protected]",
       "role": "READER"
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/tunedModels/my-tuned-model/permissions?key=[YOUR_API_KEY]"

Method: `generativelanguage.tunedModels.permissions.get`

Gets information about a specific Permission.

Endpoint: GET /v1beta3/{+name}
Description: Gets information about a specific Permission.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	Required. The resource name of the permission. Format: `tunedModels/{tuned_model}/permissions/{permission}`.

curl Example

curl "https://generativelanguage.googleapis.com/v1beta3/tunedModels/my-tuned-model/permissions/12345?key=[YOUR_API_KEY]"

Method: `generativelanguage.tunedModels.permissions.list`

Lists permissions for a specific tuned model.

Endpoint: GET /v1beta3/{+parent}/permissions
Description: Lists permissions for the specific resource.

Parameters

Name	Location	Type	Required	Description
`parent`	path	string	Yes	Required. The parent resource. Format: `tunedModels/{tuned_model}`.
`pageSize`	query	integer	No	Optional. The maximum number of `Permission`s to return.
`pageToken`	query	string	No	Optional. A page token from a previous call.

curl Example

curl "https://generativelanguage.googleapis.com/v1beta3/tunedModels/my-tuned-model/permissions?pageSize=10&key=[YOUR_API_KEY]"

Method: `generativelanguage.tunedModels.permissions.patch`

Updates a permission.

Endpoint: PATCH /v1beta3/{+name}
Description: Updates the permission.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	The permission name. Format: `tunedModels/{tuned_model}/permissions/{permission}`.
`updateMask`	query	string	Yes	Required. The list of fields to update. Currently only accepts `role`.

Request Body

The request body is a Permission object with the updated role.

curl Example

curl -X PATCH \
     -H "Content-Type: application/json" \
     -d '{
       "role": "WRITER"
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/tunedModels/my-tuned-model/permissions/12345?updateMask=role&key=[YOUR_API_KEY]"

Method: `generativelanguage.tunedModels.permissions.delete`

Deletes a permission.

Endpoint: DELETE /v1beta3/{+name}
Description: Deletes the permission.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	Required. The resource name of the permission. Format: `tunedModels/{tuned_model}/permissions/{permission}`.

curl Example

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta3/tunedModels/my-tuned-model/permissions/12345?key=[YOUR_API_KEY]"

Corpora Permissions Resource

This resource manages access control for corpora, which are collections of documents that can be used with the API. The methods are analogous to the tunedModels.permissions methods.

Method: `generativelanguage.corpora.permissions.create`

Create a permission to a specific corpus.

Endpoint: POST /v1beta3/{+parent}/permissions
Description: Create a permission to a specific resource.

Parameters

Name	Location	Type	Required	Description
`parent`	path	string	Yes	Required. The parent resource of the `Permission`. Format: `corpora/{corpus}`.

Request Body

The request body is a Permission object.

Field	Type	Required	Description
`granteeType`	string	Yes	Type of grantee (`USER`, `GROUP`, `EVERYONE`).
`emailAddress`	string	No	Email for `USER` or `GROUP` grantee types.
`role`	string	Yes	Role to grant (`READER`, `WRITER`, `OWNER`).

curl Example

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "granteeType": "USER",
       "emailAddress": "[email protected]",
       "role": "READER"
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/corpora/my-corpus-id/permissions?key=[YOUR_API_KEY]"

Method: `generativelanguage.corpora.permissions.get`

Gets information about a specific Permission for a corpus.

Endpoint: GET /v1beta3/{+name}
Description: Gets information about a specific Permission.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	Required. The resource name of the permission. Format: `corpora/{corpus}/permissions/{permission}`.

curl Example

curl "https://generativelanguage.googleapis.com/v1beta3/corpora/my-corpus-id/permissions/67890?key=[YOUR_API_KEY]"

Method: `generativelanguage.corpora.permissions.list`

Lists permissions for a specific corpus.

Endpoint: GET /v1beta3/{+parent}/permissions
Description: Lists permissions for the specific resource.

Parameters

Name	Location	Type	Required	Description
`parent`	path	string	Yes	Required. The parent resource. Format: `corpora/{corpus}`.
`pageSize`	query	integer	No	Optional. The maximum number of `Permission`s to return.
`pageToken`	query	string	No	Optional. A page token from a previous call.

curl Example

curl "https://generativelanguage.googleapis.com/v1beta3/corpora/my-corpus-id/permissions?pageSize=5&key=[YOUR_API_KEY]"

Method: `generativelanguage.corpora.permissions.patch`

Updates a permission for a corpus.

Endpoint: PATCH /v1beta3/{+name}
Description: Updates the permission.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	The permission name. Format: `corpora/{corpus}/permissions/{permission}`.
`updateMask`	query	string	Yes	Required. The list of fields to update. Currently only accepts `role`.

Request Body

The request body is a Permission object with the updated role.

curl Example

curl -X PATCH \
     -H "Content-Type: application/json" \
     -d '{
       "role": "WRITER"
     }' \
     "https://generativelanguage.googleapis.com/v1beta3/corpora/my-corpus-id/permissions/67890?updateMask=role&key=[YOUR_API_KEY]"

Method: `generativelanguage.corpora.permissions.delete`

Deletes a permission from a corpus.

Endpoint: DELETE /v1beta3/{+name}
Description: Deletes the permission.

Parameters

Name	Location	Type	Required	Description
`name`	path	string	Yes	Required. The resource name of the permission. Format: `corpora/{corpus}/permissions/{permission}`.

curl Example

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta3/corpora/my-corpus-id/permissions/67890?key=[YOUR_API_KEY]"

0wwafa/genai.md

Generative Language API v1beta3 Documentation

Authentication

API Key

Resources

Models Resource

Method: generativelanguage.models.generateMessage

Method: generativelanguage.models.countMessageTokens

Method: generativelanguage.models.get

Method: generativelanguage.models.list

Method: generativelanguage.models.generateText

Method: generativelanguage.models.embedText

Method: generativelanguage.models.batchEmbedText

Method: generativelanguage.models.countTextTokens

Tuned Models Resource

Method: generativelanguage.tunedModels.get

Method: generativelanguage.tunedModels.list

Method: generativelanguage.tunedModels.create

Method: generativelanguage.tunedModels.patch

Method: generativelanguage.tunedModels.delete

Method: generativelanguage.tunedModels.transferOwnership

Method: generativelanguage.tunedModels.generateText

Tuned Models Permissions Resource

Method: generativelanguage.tunedModels.permissions.create

Method: generativelanguage.tunedModels.permissions.get

Method: generativelanguage.tunedModels.permissions.list

Method: generativelanguage.tunedModels.permissions.patch

Method: generativelanguage.tunedModels.permissions.delete

Corpora Permissions Resource

Method: generativelanguage.corpora.permissions.create

Method: generativelanguage.corpora.permissions.get

Method: generativelanguage.corpora.permissions.list

Method: generativelanguage.corpora.permissions.patch

Method: generativelanguage.corpora.permissions.delete

Method: `generativelanguage.models.generateMessage`

Method: `generativelanguage.models.countMessageTokens`

Method: `generativelanguage.models.get`

Method: `generativelanguage.models.list`

Method: `generativelanguage.models.generateText`

Method: `generativelanguage.models.embedText`

Method: `generativelanguage.models.batchEmbedText`

Method: `generativelanguage.models.countTextTokens`

Method: `generativelanguage.tunedModels.get`

Method: `generativelanguage.tunedModels.list`

Method: `generativelanguage.tunedModels.create`

Method: `generativelanguage.tunedModels.patch`

Method: `generativelanguage.tunedModels.delete`

Method: `generativelanguage.tunedModels.transferOwnership`

Method: `generativelanguage.tunedModels.generateText`

Method: `generativelanguage.tunedModels.permissions.create`

Method: `generativelanguage.tunedModels.permissions.get`

Method: `generativelanguage.tunedModels.permissions.list`

Method: `generativelanguage.tunedModels.permissions.patch`

Method: `generativelanguage.tunedModels.permissions.delete`

Method: `generativelanguage.corpora.permissions.create`

Method: `generativelanguage.corpora.permissions.get`

Method: `generativelanguage.corpora.permissions.list`

Method: `generativelanguage.corpora.permissions.patch`

Method: `generativelanguage.corpora.permissions.delete`