API Call Responses

Os modelos Grok da XAI na plataforma de agentes do Gemini Enterprise são compatíveis com a API Responses para gerar respostas.

Nesta página, mostramos como fazer chamadas para modelos do Grok usando a API Responses.

Antes de começar

Para usar os modelos do Grok com a plataforma de agentes do Gemini Enterprise, siga estas etapas. A API da plataforma de agentes do Gemini Enterprise (aiplatform.googleapis.com) precisa estar ativada.

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

Fazer uma chamada sem streaming para a API Responses

Os exemplos a seguir mostram como fazer uma chamada sem streaming para a API Responses:

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.

Antes de executar os exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

Antes de executar este exemplo, defina a variável de ambiente OPENAI_BASE_URL ou configure as credenciais do OAuth. Para mais informações, consulte Autenticação e credenciais.

from openai import OpenAI
client = OpenAI()
response = client.responses.create(
    model="MODEL",
    input="INPUT",
    max_output_tokens=MAX_OUTPUT_TOKENS,
    stream=False,
)
print(response)
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.20-reasoning.
  • INPUT: o comando ou a entrada para o modelo.
  • MAX_OUTPUT_TOKENS: número máximo de tokens que podem ser gerados na resposta. Um token tem cerca de quatro caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.

    Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.

REST

Depois de configurar seu ambiente, use REST para testar uma solicitação de texto. O exemplo a seguir envia uma solicitação ao endpoint do modelo de editor.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID pelo ID do projeto no Google Cloud.
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.20-reasoning.
  • INPUT: o comando ou a entrada para o modelo.
  • MAX_OUTPUT_TOKENS: número máximo de tokens que podem ser gerados na resposta. Um token tem cerca de quatro caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.

    Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.

Método HTTP e URL: 

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses

Corpo JSON da solicitação:

{
  "model": "MODEL",
  "input": "INPUT",
  "max_output_tokens": MAX_OUTPUT_TOKENS,
  "stream": false
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses" | Select-Object -Expand Content

Confira abaixo um exemplo de solicitação curl completa:

curl -s -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/responses" \
  -d '{
    "model": "xai/grok-4.20-reasoning",
    "input": "Explain black holes in one short sentence.",
    "max_output_tokens": 100,
    "stream": false
  }'

Com base na definição da API Responses, uma resposta sem streaming contém um ID exclusivo, metadados do modelo, estatísticas de uso e uma matriz de saída com o texto gerado.

{
  "background": false,
  "completed_at": 1778892918,
  "created_at": 1778892916,
  "error": null,
  "frequency_penalty": 0,
  "id": "c8AHavnIMP6UifEPgIfcgAg",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {
    "system_fingerprint": "fp_39c5j0a3e9"
  },
  "model": "MODEL",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "OUTPUT_TEXT",
          "type": "output_text"
        }
      ],
      "id": "msg_c8AHavnIMP6UifEPgIfcgAg",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": "medium",
    "summary": "detailed"
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": false,
  "temperature": 0.7,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 0.95,
  "truncation": "disabled",
  "usage": {
    "extra_properties": {
      "google": {
        "traffic_type": "ON_DEMAND"
      }
    },
    "input_tokens": 335,
    "input_tokens_details": {
      "cached_tokens": 320
    },
    "num_server_side_tools_used": 0,
    "num_sources_used": 0,
    "output_tokens": 305,
    "output_tokens_details": {
      "reasoning_tokens": 284
    },
    "total_tokens": 640
  },
  "user": null
}

Fazer uma chamada de streaming para a API Responses

Os exemplos a seguir mostram como fazer uma chamada de streaming para a API Responses:

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.

Antes de executar os exemplos de código, defina a variável de ambiente GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

Antes de executar este exemplo, defina a variável de ambiente OPENAI_BASE_URL ou configure as credenciais do OAuth. Para mais informações, consulte Autenticação e credenciais.

from openai import OpenAI
client = OpenAI()
stream = client.responses.create(
    model="MODEL",
    input="INPUT",
    max_output_tokens=MAX_OUTPUT_TOKENS,
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.20-reasoning.
  • INPUT: o comando ou a entrada para o modelo.
  • MAX_OUTPUT_TOKENS: número máximo de tokens que podem ser gerados na resposta. Um token tem cerca de quatro caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.

    Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.

REST

Depois de configurar seu ambiente, use REST para testar uma solicitação de texto. O exemplo a seguir envia uma solicitação ao endpoint do modelo de editor.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID pelo ID do projeto no Google Cloud.
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.20-reasoning.
  • INPUT: o comando ou a entrada para o modelo.
  • MAX_OUTPUT_TOKENS: número máximo de tokens que podem ser gerados na resposta. Um token tem cerca de quatro caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.

    Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.

Método HTTP e URL: 

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses

Corpo JSON da solicitação:

{
  "model": "MODEL",
  "input": "INPUT",
  "max_output_tokens": MAX_OUTPUT_TOKENS,
  "stream": true
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses" | Select-Object -Expand Content
 

A seguir