OpenAI compatibility

Gemini models are accessible using the OpenAI libraries (Python and TypeScript / Javascript) along with the REST API, by updating three lines of code and using your Gemini API key. Read more about this feature in the compatibility guide.

Method: chatCompletions

Generates a set of responses from the model given a chat history input.

Endpoint

post https://generativelanguage.googleapis.com/v1beta:chatCompletions

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

Fields
model string

Required. The name of the Model to use for generating the completion. The model name will prefixed by "models/" if no slash appears in it.

messages[] object (Struct format)

Required. The chat history to use for generating the completion. Supports single and multi-turn queries. Note: This is a polymorphic field, it is deserialized to a InternalChatMessage.

stream boolean

Optional. Whether to stream the response or return a single response.

If true, the "object" field in the response will be "chat.completion.chunk". Otherwise it will be "chat.completion".

streamOptions object (StreamOptions)

Optional. Options for streaming requests.

tools[] object (ChatTool)

Optional. The set of tools the model can generate calls for. Each tool declares its signature.

toolChoice value (Value format)

Optional. Controls whether the model should use a tool or not, and which tool to use. Can be either: - The string "none", to disable tools. - The string "auto", to let the model decide. - The string "required", to force the model to use a tool. - A function name descriptor object, specifying the tool to use. The last option follows the following schema: { "type": "function", "function": {"name" : "the_function_name"} }

n integer

Optional. Amount of candidate completions to generate. Must be a positive integer. Defaults to 1 if not set.

stop value (Value format)

Optional. The set of character sequences that will stop output generation. Note: This is a polymorphic field. It is meant to contain a string or repeated strings.

maxCompletionTokens integer

Optional. The maximum number of tokens to include in a response candidate. Must be a positive integer.

maxTokens integer

Optional. The maximum number of tokens to include in a response candidate. Must be a positive integer. This field is deprecated by the SDK.

temperature number

Optional. Controls the randomness of the output.

topP number

Optional. The maximum cumulative probability of tokens to consider when sampling.

responseFormat object (ResponseFormat)

Optional. Defines the format of the response. If not set, the response will be formatted as text.

Response body

If successful, the response is a generic HTTP response whose format is defined by the method.

Method: embeddings

Generates embeddings from the model given an input.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/embeddings

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

Fields
input value (Value format)

Required. The input to generate embeddings for. Can be a string, or a list of strings. The SDK supports a list of numbers and list of list of numbers, but this is not yet implemented.

model string

Required. Model to generate the embeddings for.

encodingFormat string

Optional. The format of the encoding. Must be either "float" or "base64".

dimensions integer

Optional. Dimensional size of the generated embeddings.

Response body

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

Method: listModels

Lists the currently available models.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/listModels

The URL uses gRPC Transcoding syntax.

Request body

The request body must be empty.

Response body

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

Method: chat.completions

Generates a set of responses from the model given a chat history input.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/chat/completions

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

Fields
model string

Required. The name of the Model to use for generating the completion. The model name will prefixed by "models/" if no slash appears in it.

messages[] object (Struct format)

Required. The chat history to use for generating the completion. Supports single and multi-turn queries. Note: This is a polymorphic field, it is deserialized to a InternalChatMessage.

stream boolean

Optional. Whether to stream the response or return a single response.

If true, the "object" field in the response will be "chat.completion.chunk". Otherwise it will be "chat.completion".

streamOptions object (StreamOptions)

Optional. Options for streaming requests.

tools[] object (ChatTool)

Optional. The set of tools the model can generate calls for. Each tool declares its signature.

toolChoice value (Value format)

Optional. Controls whether the model should use a tool or not, and which tool to use. Can be either: - The string "none", to disable tools. - The string "auto", to let the model decide. - The string "required", to force the model to use a tool. - A function name descriptor object, specifying the tool to use. The last option follows the following schema: { "type": "function", "function": {"name" : "the_function_name"} }

n integer

Optional. Amount of candidate completions to generate. Must be a positive integer. Defaults to 1 if not set.

stop value (Value format)

Optional. The set of character sequences that will stop output generation. Note: This is a polymorphic field. It is meant to contain a string or repeated strings.

maxCompletionTokens integer

Optional. The maximum number of tokens to include in a response candidate. Must be a positive integer.

maxTokens integer

Optional. The maximum number of tokens to include in a response candidate. Must be a positive integer. This field is deprecated by the SDK.

temperature number

Optional. Controls the randomness of the output.

topP number

Optional. The maximum cumulative probability of tokens to consider when sampling.

responseFormat object (ResponseFormat)

Optional. Defines the format of the response. If not set, the response will be formatted as text.

Response body

If successful, the response is a generic HTTP response whose format is defined by the method.

Method: embeddings.generate

Generates embeddings from the model given an input.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/embeddings:generate

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

Fields
input value (Value format)

Required. The input to generate embeddings for. Can be a string, or a list of strings. The SDK supports a list of numbers and list of list of numbers, but this is not yet implemented.

model string

Required. Model to generate the embeddings for.

encodingFormat string

Optional. The format of the encoding. Must be either "float" or "base64".

dimensions integer

Optional. Dimensional size of the generated embeddings.

Response body

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

Method: openai.chat.completions

Generates a set of responses from the model given a chat history input.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/openai/chat/completions

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

Fields
model string

Required. The name of the Model to use for generating the completion. The model name will prefixed by "models/" if no slash appears in it.

messages[] object (Struct format)

Required. The chat history to use for generating the completion. Supports single and multi-turn queries. Note: This is a polymorphic field, it is deserialized to a InternalChatMessage.

stream boolean

Optional. Whether to stream the response or return a single response.

If true, the "object" field in the response will be "chat.completion.chunk". Otherwise it will be "chat.completion".

streamOptions object (StreamOptions)

Optional. Options for streaming requests.

tools[] object (ChatTool)

Optional. The set of tools the model can generate calls for. Each tool declares its signature.

toolChoice value (Value format)

Optional. Controls whether the model should use a tool or not, and which tool to use. Can be either: - The string "none", to disable tools. - The string "auto", to let the model decide. - The string "required", to force the model to use a tool. - A function name descriptor object, specifying the tool to use. The last option follows the following schema: { "type": "function", "function": {"name" : "the_function_name"} }

n integer

Optional. Amount of candidate completions to generate. Must be a positive integer. Defaults to 1 if not set.

stop value (Value format)

Optional. The set of character sequences that will stop output generation. Note: This is a polymorphic field. It is meant to contain a string or repeated strings.

maxCompletionTokens integer

Optional. The maximum number of tokens to include in a response candidate. Must be a positive integer.

maxTokens integer

Optional. The maximum number of tokens to include in a response candidate. Must be a positive integer. This field is deprecated by the SDK.

temperature number

Optional. Controls the randomness of the output.

topP number

Optional. The maximum cumulative probability of tokens to consider when sampling.

responseFormat object (ResponseFormat)

Optional. Defines the format of the response. If not set, the response will be formatted as text.

Response body

If successful, the response is a generic HTTP response whose format is defined by the method.

Method: openai.embeddings

Generates embeddings from the model given an input.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/openai/embeddings

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

Fields
input value (Value format)

Required. The input to generate embeddings for. Can be a string, or a list of strings. The SDK supports a list of numbers and list of list of numbers, but this is not yet implemented.

model string

Required. Model to generate the embeddings for.

encodingFormat string

Optional. The format of the encoding. Must be either "float" or "base64".

dimensions integer

Optional. Dimensional size of the generated embeddings.

Response body

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

Method: openai.models

Lists the currently available models.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/openai/models

The URL uses gRPC Transcoding syntax.

Request body

The request body must be empty.

Response body

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

ChatTool

A tool that the model can generate calls for.

Fields
function object (ChatFunction)

Required. The name of the tool.

type string

Required. Required, must be "function".

JSON representation 
{
  "function": {
    object (ChatFunction)
  },
  "type": string
}

ChatFunction

A function that the model can generate calls for.

Fields
name string

Required. The name of the function.

description string

Optional. A description of the function.

parameters object (Struct format)

Optional. The parameters of the function.

strict boolean

Optional. Whether the schema validation is strict. If true, the model will fail if the schema is not valid. NOTE: This parameter is currently ignored.

JSON representation 
{
  "name": string,
  "description": string,
  "parameters": {
    object
  },
  "strict": boolean
}

GenerateEmbeddingsResponse

Response for embedding generation.

Fields
object string

Output only. Always "embedding", required by the SDK.

data[] object (GenerateEmbeddingsEmbedding)

Output only. A list of the requested embeddings.

model string

Output only. Model used to generate the embeddings.

JSON representation 
{
  "object": string,
  "data": [
    {
      object (GenerateEmbeddingsEmbedding)
    }
  ],
  "model": string
}

GenerateEmbeddingsEmbedding

An embedding vector generated by the model.

Fields
object string

Output only. Always "embedding", required by the SDK.

index integer

Output only. Index of the embedding in the list of embeddings.

embedding value (Value format)

Output only. The embedding vector generated for the input. Can be either a list of floats or a base64 string encoding the a list of floats with C-style layout (Numpy compatible).

JSON representation 
{
  "object": string,
  "index": integer,
  "embedding": value
}

HttpBody

Message that represents an arbitrary HTTP body. It should only be used for payload formats that can't be represented as JSON, such as raw binary or an HTML page.

This message can be used both in streaming and non-streaming API methods in the request as well as the response.

It can be used as a top-level request field, which is convenient if one wants to extract parameters from either the URL or HTTP template into the request fields and also want access to the raw HTTP body.

Example:

message GetResourceRequest {
  // A unique request id.
  string requestId = 1;

  // The raw HTTP body is bound to this field.
  google.api.HttpBody http_body = 2;

}

service ResourceService {
  rpc GetResource(GetResourceRequest)
    returns (google.api.HttpBody);
  rpc UpdateResource(google.api.HttpBody)
    returns (google.protobuf.Empty);

}

Example with streaming methods:

service CaldavService {
  rpc GetCalendar(stream google.api.HttpBody)
    returns (stream google.api.HttpBody);
  rpc UpdateCalendar(stream google.api.HttpBody)
    returns (stream google.api.HttpBody);

}

Use of this type only changes how the request and response bodies are handled, all other features will continue to work unchanged.

Fields
contentType string

The HTTP Content-Type header value specifying the content type of the body.

data string (bytes format)

The HTTP request/response body as raw binary.

A base64-encoded string.

extensions[] object

Application specific response metadata. Must be set in the first response for streaming APIs.

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 
{
  "contentType": string,
  "data": string,
  "extensions": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}

ResponseFormat

Defines the format of the response.

Fields
type string

Required. Type of the response. Can be either: - "text": Format the response as text. - "json_object": Format the response as a JSON object. - "jsonSchema": Format the response as a JSON object following the given schema.

jsonSchema object (ResponseFormatSchema)

Optional. The JSON schema to follow. Only used if type is "jsonSchema".

JSON representation 
{
  "type": string,
  "jsonSchema": {
    object (ResponseFormatSchema)
  }
}

ResponseFormatSchema

Schema for the response.

Fields
description string

Optional. Description of the object represented by the schema.

name string

Required. Name of the object type represented by the schema.

strict boolean

Optional. Whether the schema validation is strict. If true, the model will fail if the schema is not valid. NOTE: This parameter is currently ignored.

schema object (Struct format)

Optional. The JSON schema to follow.

JSON representation 
{
  "description": string,
  "name": string,
  "strict": boolean,
  "schema": {
    object
  }
}

SdkListModelsResponse

Response for list models.

Fields
object string

Output only. Always "list", required by the SDK.

data[] object (SdkModel)

Output only. A list of the requested embeddings.

JSON representation 
{
  "object": string,
  "data": [
    {
      object (SdkModel)
    }
  ]
}

SdkModel

The model object.

Fields
id string

Output only. Id of the model.

object string

Output only. Always "model", required by the SDK.

created string (int64 format)

Output only. The Unix timestamp (in seconds) when the model was created.

owned_by string

Output only. The organization that owns the model.

JSON representation 
{
  "id": string,
  "object": string,
  "created": string,
  "owned_by": string
}

StreamOptions

Options for streaming requests.

Fields
includeUsage boolean

Optional. If set, include usage statistics in the response.

JSON representation 
{
  "includeUsage": boolean
}