Exemplos

Chamar o Gemini com a API Chat Completions

O exemplo a seguir mostra como enviar solicitações sem streaming:

REST

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/openapi/chat/completions \
  -d '{
    "model": "google/${MODEL_ID}",
    "messages": [{
      "role": "user",
      "content": "Write a story about a magic backpack."
    }]
  }'

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido da Agent Platform: como usar bibliotecas de cliente.

Para autenticar no Agent Platform, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

print(response)

O exemplo a seguir mostra como enviar solicitações de streaming para um Modelo do Gemini usando a API Chat Completions:

REST

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/openapi/chat/completions \
  -d '{
    "model": "google/${MODEL_ID}",
    "stream": true,
    "messages": [{
      "role": "user",
      "content": "Write a story about a magic backpack."
    }]
  }'

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido da Agent Platform: como usar bibliotecas de cliente.

Para autenticar no Agent Platform, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True,
)
for chunk in response:
    print(chunk)

Enviar um comando e uma imagem para a API Gemini na Gemini Enterprise Agent Platform

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido da Agent Platform: como usar bibliotecas de cliente.

Para autenticar no Agent Platform, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe the following image:"},
                {
                    "type": "image_url",
                    "image_url": "gs://cloud-samples-data/generative-ai/image/scones.jpg",
                },
            ],
        }
    ],
)

print(response)

Chamar um modelo autoimplantado com a API Chat Completions

O exemplo a seguir mostra como enviar solicitações sem streaming:

REST

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/endpoints/${ENDPOINT}/chat/completions \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Write a story about a magic backpack."
    }]
  }'

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido da Agent Platform: como usar bibliotecas de cliente.

Para autenticar no Agent Platform, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"
# model_id = "gemma-2-9b-it"
# endpoint_id = "YOUR_ENDPOINT_ID"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/{endpoint_id}",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)
print(response)

O exemplo a seguir mostra como enviar solicitações de streaming para um modelo autoimplantado usando a API Chat Completions:

REST

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/endpoints/${ENDPOINT}/chat/completions \
    -d '{
      "stream": true,
      "messages": [{
        "role": "user",
        "content": "Write a story about a magic backpack."
      }]
    }'

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido da Agent Platform: como usar bibliotecas de cliente.

Para autenticar no Agent Platform, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"
# model_id = "gemma-2-9b-it"
# endpoint_id = "YOUR_ENDPOINT_ID"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/{endpoint_id}",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True,
)
for chunk in response:
    print(chunk)

Exemplos de extra_body

É possível usar o SDK ou a API REST para transmitir extra_body.

Adicionar thought_tag_marker

{
  ...,
  "extra_body": {
     "google": {
       ...,
       "thought_tag_marker": "..."
     }
   }
}

Adicionar o extra_body usando o SDK

client.chat.completions.create(
  ...,
  extra_body = {
    'extra_body': { 'google': { ... } }
  },
)

Exemplos de extra_content

É possível preencher esse campo usando a API REST diretamente.

extra_content com a string content

{
  "messages": [
    { "role": "...", "content": "...", "extra_content": { "google": { ... } } }
  ]
}

extra_content por mensagem

{
  "messages": [
    {
      "role": "...",
      "content": [
        { "type": "...", ..., "extra_content": { "google": { ... } } }
      ]
    }
}

Chamada de ferramenta por extra_content

{
  "messages": [
    {
      "role": "...",
      "tool_calls": [
        {
          ...,
          "extra_content": { "google": { ... } }
        }
      ]
    }
  ]
}

Exemplos de solicitações de curl

É possível usar essas solicitações curl diretamente, sem passar pelo SDK.

Use o thinking_config com extra_body

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/endpoints/openapi/chat/completions \
  -d '{ \
    "model": "google/gemini-2.5-flash-preview-04-17", \
    "messages": [ \
      { "role": "user", \
      "content": [ \
        { "type": "text", \
          "text": "Are there any primes number of the form n*ceil(log(n))" \
        }] }], \
    "extra_body": { \
      "google": { \
          "thinking_config": { \
          "include_thoughts": true, "thinking_budget": 10000 \
        }, \
        "thought_tag_marker": "think" } }, \
    "stream": true }'

Usar stream_function_call_arguments

Exemplo de solicitação:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/endpoints/openapi/chat/completions \
  -d '{
  "model": "google/gemini-3.1-pro-preview", \
  "messages": [ \
    { "role": "user", "content": "What is the weather like in Boston and New Delhi today?" } ], \
  "tools": [ \
    { \
      "type": "function", \
      "function": { \
        "name": "get_current_weather", \
        "description": "Get the current weather in a given location", \
        "parameters": { \
          "type": "object", \
          "properties": { \
            "location": { \
              "type": "string", \
              "description": "The city and state, e.g. San Francisco, CA" \
            }, \
            "unit": { \
              "type": "string", \
              "enum": [ \
                "celsius", \
                "fahrenheit" \
              ] \
            } \
          }, \
          "required": [ \
            "location", \
            "unit" \
          ] \
        } \
      } \
    } \
  ], \
  "extra_body": { \
    "google": { \
      "stream_function_call_arguments": true \
    } \
  }, \
  "stream": true \
}'

Exemplos de respostas:

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"extra_content":{"google":{"thought_signature":"..."}},"function":{"arguments":"","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":1,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"{\"location\":\"Boston, MA","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"\"","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":",\"unit\":\"celsius","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"\"","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"}","name":"get_current_weather"},"id":"function-call-c855348a-459a-46a4-a8ad-aa0a4e7c3563","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":0,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"{\"location\":\"New Delhi, India","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":1,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"\"","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":1,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":",\"unit\":\"celsius","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":1,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"\"","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":1,"type":"function"}]},"index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":""}

data: {"choices":[{"delta":{"role":"assistant","tool_calls":[{"function":{"arguments":"}","name":"get_current_weather"},"id":"function-call-df0d087c-ad74-46f1-ba4a-9353cbf288a8","index":1,"type":"function"}]},"finish_reason":"tool_calls","index":0,"logprobs":null}],"created":1770850461,"id":"nQiNafGyF5rw998PstqooAY","model":"google/gemini-3.1-pro-preview","object":"chat.completion.chunk","system_fingerprint":"","usage":{"completion_tokens":45,"completion_tokens_details":{"reasoning_tokens":504},"extra_properties":{"google":{"traffic_type":"PROVISIONED_THROUGHPUT"}},"prompt_tokens":27,"total_tokens":576}}

data: [DONE]

Geração de imagens

Para manter a compatibilidade com o formato de resposta da OpenAI, o campo audio da resposta é preenchido explicitamente com um extra_content.google.mime_type que indica o tipo MIME do resultado.

Exemplo de solicitação:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/endpoints/openapi/chat/completions \
  -d '{"model":"google/gemini-3-pro-image-preview", "messages":[{ "role": "user", "content": "Generate an image of a cat." }], "modalities": ["image"] }'

Exemplo de resposta:

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "audio": {
          "data": "<BASE64_BYTES>",
          "extra_content": {
            "google": {
              "mime_type": "image/png"
            }
          }
        },
        "content": null,
        "extra_content": {
          "google": {
            "thought_signature": "..."
          }
        },
        "role": "assistant"
      }
    }
  ],
  "created": 1770850692,
  "id": "hAmNaZb8BZOX4_UPlNXoEA",
  "model": "google/gemini-3-pro-image-preview",
  "object": "chat.completion",
  "system_fingerprint": "",
  "usage": {
    "completion_tokens": 1120,
    "completion_tokens_details": {
      "reasoning_tokens": 251
    },
    "extra_properties": {
      "google": {
        "traffic_type": "PROVISIONED_THROUGHPUT"
      }
    },
    "prompt_tokens": 7,
    "total_tokens": 1378
  }
}

Solicitações multimodais

A API Chat Completions é compatível com vários tipos de entrada multimodal, incluindo áudio e vídeo.

Usar image_url para transmitir dados de imagem

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/endpoints/openapi/chat/completions \
  -d '{ \
    "model": "google/gemini-2.0-flash-001", \
    "messages": [{ "role": "user", "content": [ \
      { "type": "text", "text": "Describe this image" }, \
      { "type": "image_url", "image_url": "gs://cloud-samples-data/generative-ai/image/scones.jpg" }] }] }'

Usar input_audio para transmitir dados de áudio

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/endpoints/openapi/chat/completions \
  -d '{ \
    "model": "google/gemini-2.0-flash-001", \
    "messages": [ \
      { "role": "user", \
        "content": [ \
          { "type": "text", "text": "Describe this: " }, \
          { "type": "input_audio", "input_audio": { \
            "format": "audio/mp3", \
            "data": "gs://cloud-samples-data/generative-ai/audio/pixel.mp3" } }] }] }'

Respostas de funções multimodais

Exemplo de solicitação:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/endpoints/openapi/chat/completions \
  -d '{ \
    "model": "google/gemini-3.1-pro-preview", \
    "messages": [ \
      { "role": "user", "content": "Show me the green shirt I ordered last month." }, \
      { \
        "role": "assistant", \
        "tool_calls": [ \
          { \
            "extra_content": { \
              "google": { \
                "thought_signature": "<THOUGHT_SIGNATURE>" \
              } \
            }, \
            "function": { \
              "arguments": "{\"item_name\":\"green shirt\"}", \
              "name": "get_image" \
            }, \
            "id": "function-call-a350228d-0283-4792-8bfa-40da064fb959", \
            "type": "function" \
          } \
        ] \
      }, \
      { \
        "role": "tool", \
        "tool_call_id": "function-call-a350228d-0283-4792-8bfa-40da064fb959", \
        "content": "{\"image_ref\":{\"$ref\":\"dress.jpg\"}}", \
        "extra_content": { \
          "google": { \
            "parts": [ \
              { \
                "file_data": { \
                  "mime_type": "image/jpg", \
                  "display_name": "dress.jpg", \
                  "file_uri": "gs://cloud-samples-data/generative-ai/image/dress.jpg" \
                } \
              } \
            ] \
          } \
        } \
      } \
    ], \
    "tools": [ \
      { \
        "type": "function", \
        "function": { \
          "name": "get_image", \
          "description": "Retrieves the image file reference for a specific order item.", \
          "parameters": { \
            "type": "object", \
            "properties": { \
              "item_name": { \
                "type": "string", \
                "description": "The name or description of the item ordered (e.g., 'green shirt')." \
              } \
            }, \
            "required": [ \
              "item_name" \
            ] \
          } \
        } \
      } \
    ] \
  }'

Exemplo de resposta:

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "Here is the image of the green shirt you ordered.",
        "role": "assistant"
      }
    }
  ],
  "created": 1770852204,
  "id": "bA-NacCPKoae_9MPsNCn6Qc",
  "model": "google/gemini-3.1-pro-preview",
  "object": "chat.completion",
  "system_fingerprint": "",
  "usage": {
    "completion_tokens": 16,
    "extra_properties": {
      "google": {
        "traffic_type": "ON_DEMAND"
      }
    },
    "prompt_tokens": 1139,
    "total_tokens": 1155
  }
}

Resposta estruturada

Use o parâmetro response_format para receber uma saída estruturada.

Exemplo usando o SDK

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="google/gemini-2.5-flash-preview-04-17",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
)

print(completion.choices[0].message.parsed)

Como usar o endpoint global no modo compatível com a OpenAI

O exemplo a seguir mostra como usar o endpoint global no modo compatível com a OpenAI:

REST

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/endpoints/openapi/chat/completions\
  -d '{ \
    "model": "google/gemini-2.0-flash-001", \
    "messages": [ \
    {"role": "user", \
      "content": "Hello World" \
      }] \
      }'

A seguir