API Call Responses

Os modelos Grok da XAI na Gemini Enterprise Agent Platform são compatíveis com a API Responses para gerar respostas.

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

Antes de começar

Para usar os modelos do Grok com a Gemini Enterprise Agent Platform, siga as etapas abaixo. A API Gemini Enterprise Agent Platform (aiplatform.googleapis.com) precisa estar ativada.

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

  6. Verify that billing is enabled for your Google Cloud project.

  7. 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 estado para a API Responses

O valor padrão de store é false. Portanto, as solicitações são sem estado, a menos que você defina store como true. Os exemplos a seguir definem store como false (ou False em Python) explicitamente.

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 este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

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

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.

import google.auth
import google.auth.transport.requests
from openai import OpenAI
credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
credentials.refresh(google.auth.transport.requests.Request())
client = OpenAI(
    base_url="https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi",
    api_key=credentials.token,
)
response = client.responses.create(
    model="MODEL",
    input="INPUT",
    max_output_tokens=MAX_OUTPUT_TOKENS,
    stream=False,
    store=False,
)
print(response)
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.7.
  • 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 o ambiente, use REST para testar um comando 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: o ID do projeto do Google Cloud .
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.7.
  • 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,
  "store": 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 application-default 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 application-default 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

O exemplo a seguir mostra uma solicitação curl completa:

curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default 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.7",
    "input": "Explain black holes in one short sentence.",
    "max_output_tokens": 100,
    "stream": false,
    "store": false
  }'

Com base na definição da API Responses, uma resposta sem streaming vai conter 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 este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

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

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.

import google.auth
import google.auth.transport.requests
from openai import OpenAI
credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
credentials.refresh(google.auth.transport.requests.Request())
client = OpenAI(
    base_url="https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi",
    api_key=credentials.token,
)
stream = client.responses.create(
    model="MODEL",
    input="INPUT",
    max_output_tokens=MAX_OUTPUT_TOKENS,
    stream=True,
    store=False,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.7.
  • 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 o ambiente, use REST para testar um comando 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: o ID do projeto do Google Cloud .
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.7.
  • 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,
  "store": 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 application-default 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 application-default 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
 

Fazer uma chamada com estado para a API Responses

Para fazer solicitações com estado, configure o Serviço de Políticas da Organização para permitir que elas sejam feitas. Especificamente, atualize a restrição constraints/vertexai.allowedPartnerModelFeatures adicionando publishers/xai/models/MODEL_NAME:stateful_responses_api aos valores permitidos (por exemplo, publishers/xai/models/grok-4.7:stateful_responses_api). Para mais informações, consulte Controlar o acesso ao modelo.

A API Responses é compatível com conversas multiturno usando solicitações com estado. O valor padrão de store é false. Portanto, para fazer uma solicitação com estado, é necessário definir explicitamente store como true. Em uma conversa com estado, é possível fazer referência a uma resposta anterior fornecendo o id dela no campo previous_response_id.

Criar uma resposta

Os exemplos a seguir mostram uma conversa de duas interações usando a API Responses:

Turno 1: solicitação inicial

Na primeira vez, faça uma solicitação com store definido como true. Se você omitir o parâmetro store, o padrão será false, e a resposta não será armazenada.

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

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

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.

import google.auth
import google.auth.transport.requests
from openai import OpenAI
credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
credentials.refresh(google.auth.transport.requests.Request())
client = OpenAI(
    base_url="https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi",
    api_key=credentials.token,
)
response = client.responses.create(
    model="MODEL",
    input="randomly pick 3 colors, just return the words of the colors",
    store=True,
)
print(response)
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.7.

Exemplo de resposta para o Turno 1:

{
  "background": false,
  "completed_at": 1793834418,
  "created_at": 1793834418,
  "error": null,
  "frequency_penalty": 0,
  "id": "5f76a045-71d9-45af-8b07-1f2feae0675a",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {
    "system_fingerprint": "fp_grok47_0"
  },
  "model": "xai/grok-4.7",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "cerulean amber violet",
          "type": "output_text"
        }
      ],
      "id": "msg_5f76a045-71d9-45af-8b07-1f2feae0675a",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": "high",
    "summary": "detailed"
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": true,
  "temperature": 0.7,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 0.95,
  "truncation": "disabled",
  "usage": {
    "context_details": {
      "input_tokens": 220,
      "output_tokens": 144
    },
    "extra_properties": {
      "google": {
        "traffic_type": "ON_DEMAND"
      }
    },
    "input_tokens": 220,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "num_server_side_tools_used": 0,
    "num_sources_used": 0,
    "output_tokens": 144,
    "output_tokens_details": {
      "reasoning_tokens": 139
    },
    "total_tokens": 364
  },
  "user": null
}

REST

Depois de configurar o ambiente, use REST para testar um comando 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: o ID do projeto do Google Cloud .
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.7.

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": "randomly pick 3 colors, just return the words of the colors",
  "store": 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 application-default 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 application-default 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

O exemplo a seguir mostra uma solicitação curl completa:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default 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.7",
    "input": "randomly pick 3 colors, just return the words of the colors",
    "store": true
  }'

Exemplo de resposta para o Turno 1:

{
  "background": false,
  "completed_at": 1793834418,
  "created_at": 1793834418,
  "error": null,
  "frequency_penalty": 0,
  "id": "5f76a045-71d9-45af-8b07-1f2feae0675a",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {
    "system_fingerprint": "fp_grok47_0"
  },
  "model": "xai/grok-4.7",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "cerulean amber violet",
          "type": "output_text"
        }
      ],
      "id": "msg_5f76a045-71d9-45af-8b07-1f2feae0675a",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": "high",
    "summary": "detailed"
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": true,
  "temperature": 0.7,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 0.95,
  "truncation": "disabled",
  "usage": {
    "context_details": {
      "input_tokens": 220,
      "output_tokens": 144
    },
    "extra_properties": {
      "google": {
        "traffic_type": "ON_DEMAND"
      }
    },
    "input_tokens": 220,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "num_server_side_tools_used": 0,
    "num_sources_used": 0,
    "output_tokens": 144,
    "output_tokens_details": {
      "reasoning_tokens": 139
    },
    "total_tokens": 364
  },
  "user": null
}

Turno 2: solicitação de acompanhamento

No segundo turno, faça referência ao ID da resposta anterior no parâmetro previous_response_id. Defina store como true se você também quiser armazenar essa resposta, por exemplo, para continuar a conversa ou recuperá-la mais tarde.

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

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

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.

import google.auth
import google.auth.transport.requests
from openai import OpenAI
credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
credentials.refresh(google.auth.transport.requests.Request())
client = OpenAI(
    base_url="https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi",
    api_key=credentials.token,
)
response = client.responses.create(
    model="MODEL",
    input="What is the second color?",
    previous_response_id="PREVIOUS_RESPONSE_ID",
    store=True,
)
print(response)
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.7.
  • PREVIOUS_RESPONSE_ID: o ID da resposta anterior para continuar a conversa.

Exemplo de resposta para a rodada 2:

{
  "background": false,
  "completed_at": 1793835029,
  "created_at": 1793835029,
  "error": null,
  "frequency_penalty": 0,
  "id": "ee8b6aa6-777e-4aa2-8db4-46bbfe84491b",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {
    "system_fingerprint": "fp_grok47_0"
  },
  "model": "xai/grok-4.7",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "amber",
          "type": "output_text"
        }
      ],
      "id": "msg_ee8b6aa6-777e-4aa2-8db4-46bbfe84491b",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": "5f76a045-71d9-45af-8b07-1f2feae0675a",
  "prompt_cache_key": null,
  "reasoning": {
    "effort": "high",
    "summary": "detailed"
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": true,
  "temperature": 0.7,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 0.95,
  "truncation": "disabled",
  "usage": {
    "context_details": {
      "input_tokens": 239,
      "output_tokens": 41
    },
    "extra_properties": {
      "google": {
        "traffic_type": "ON_DEMAND"
      }
    },
    "input_tokens": 239,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "num_server_side_tools_used": 0,
    "num_sources_used": 0,
    "output_tokens": 41,
    "output_tokens_details": {
      "reasoning_tokens": 40
    },
    "total_tokens": 280
  },
  "user": null
}

REST

Depois de configurar o ambiente, use REST para testar um comando 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: o ID do projeto do Google Cloud .
  • MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.7.
  • PREVIOUS_RESPONSE_ID: o ID da resposta anterior.

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": "What is the second color?",
  "previous_response_id": "PREVIOUS_RESPONSE_ID",
  "store": 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 application-default 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 application-default 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

O exemplo a seguir mostra uma solicitação curl completa:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default 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.7",
    "input": "What is the second color?",
    "previous_response_id": "5f76a045-71d9-45af-8b07-1f2feae0675a",
    "store": true
  }'

Exemplo de resposta para a rodada 2:

{
  "background": false,
  "completed_at": 1793835029,
  "created_at": 1793835029,
  "error": null,
  "frequency_penalty": 0,
  "id": "ee8b6aa6-777e-4aa2-8db4-46bbfe84491b",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {
    "system_fingerprint": "fp_grok47_0"
  },
  "model": "xai/grok-4.7",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "amber",
          "type": "output_text"
        }
      ],
      "id": "msg_ee8b6aa6-777e-4aa2-8db4-46bbfe84491b",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": "5f76a045-71d9-45af-8b07-1f2feae0675a",
  "prompt_cache_key": null,
  "reasoning": {
    "effort": "high",
    "summary": "detailed"
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": true,
  "temperature": 0.7,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 0.95,
  "truncation": "disabled",
  "usage": {
    "context_details": {
      "input_tokens": 239,
      "output_tokens": 41
    },
    "extra_properties": {
      "google": {
        "traffic_type": "ON_DEMAND"
      }
    },
    "input_tokens": 239,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "num_server_side_tools_used": 0,
    "num_sources_used": 0,
    "output_tokens": 41,
    "output_tokens_details": {
      "reasoning_tokens": 40
    },
    "total_tokens": 280
  },
  "user": null
}

Receba uma resposta

É possível recuperar uma resposta gerada anteriormente pelo ID.

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

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

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.

import json
import google.auth
import google.auth.transport.requests
from openai import OpenAI
credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
credentials.refresh(google.auth.transport.requests.Request())
client = OpenAI(
    base_url="https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi",
    api_key=credentials.token,
)
response_id = "RESPONSE_ID"
retrieved_response = client.responses.retrieve(response_id)
print(json.dumps(retrieved_response.model_dump(), indent=2))
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • RESPONSE_ID: o ID da resposta a ser recuperada.

Exemplo de resposta:

{
  "background": false,
  "completed_at": 1793834418,
  "created_at": 1793834418,
  "error": null,
  "frequency_penalty": 0,
  "id": "5f76a045-71d9-45af-8b07-1f2feae0675a",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {
    "system_fingerprint": "fp_grok47_0"
  },
  "model": "xai/grok-4.7",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "cerulean amber violet",
          "type": "output_text"
        }
      ],
      "id": "msg_5f76a045-71d9-45af-8b07-1f2feae0675a",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": "high",
    "summary": "detailed"
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": true,
  "temperature": 0.7,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 0.95,
  "truncation": "disabled",
  "usage": {
    "context_details": {
      "input_tokens": 220,
      "output_tokens": 144
    },
    "extra_properties": {
      "google": {
        "traffic_type": "ON_DEMAND"
      }
    },
    "input_tokens": 220,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "num_server_side_tools_used": 0,
    "num_sources_used": 0,
    "output_tokens": 144,
    "output_tokens_details": {
      "reasoning_tokens": 139
    },
    "total_tokens": 364
  },
  "user": null
}

REST

Depois de configurar o ambiente, use REST para testar um comando 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: o ID do projeto do Google Cloud .
  • RESPONSE_ID: o ID da resposta a ser recuperada.

Método HTTP e URL:

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

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

curl

Execute o seguinte comando:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses/RESPONSE_ID"

PowerShell

Execute o seguinte comando:

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

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses/RESPONSE_ID" | Select-Object -Expand Content

O exemplo a seguir mostra uma solicitação curl completa:

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses/5f76a045-71d9-45af-8b07-1f2feae0675a"

Exemplo de resposta:

{
  "background": false,
  "completed_at": 1793834418,
  "created_at": 1793834418,
  "error": null,
  "frequency_penalty": 0,
  "id": "5f76a045-71d9-45af-8b07-1f2feae0675a",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {
    "system_fingerprint": "fp_grok47_0"
  },
  "model": "xai/grok-4.7",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "cerulean amber violet",
          "type": "output_text"
        }
      ],
      "id": "msg_5f76a045-71d9-45af-8b07-1f2feae0675a",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": "high",
    "summary": "detailed"
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": true,
  "temperature": 0.7,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 0.95,
  "truncation": "disabled",
  "usage": {
    "context_details": {
      "input_tokens": 220,
      "output_tokens": 144
    },
    "extra_properties": {
      "google": {
        "traffic_type": "ON_DEMAND"
      }
    },
    "input_tokens": 220,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "num_server_side_tools_used": 0,
    "num_sources_used": 0,
    "output_tokens": 144,
    "output_tokens_details": {
      "reasoning_tokens": 139
    },
    "total_tokens": 364
  },
  "user": null
}

Excluir uma resposta

É possível excluir uma resposta gerada anteriormente pelo ID dela.

Depois de excluir uma resposta, não é possível recuperá-la nem usar o ID dela como o previous_response_id em uma nova solicitação. A exclusão de uma resposta não remove o conteúdo dela das respostas posteriores na mesma conversa: cada resposta que faz referência a ela por meio de previous_response_id mantém esse conteúdo como contexto até que você também exclua essa resposta. Para remover uma conversa inteira, exclua todas as respostas armazenadas nela.

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

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

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.

import google.auth
import google.auth.transport.requests
from openai import OpenAI
credentials, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
credentials.refresh(google.auth.transport.requests.Request())
client = OpenAI(
    base_url="https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi",
    api_key=credentials.token,
)
response_id = "RESPONSE_ID"
delete_response = client.responses.delete(response_id)
print(delete_response)
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • RESPONSE_ID: o ID da resposta a ser excluída.

Exemplo de resposta:

{
  "deleted": true,
  "id": "5f76a045-71d9-45af-8b07-1f2feae0675a",
  "object": "response"
}

REST

Depois de configurar o ambiente, use REST para testar um comando 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: o ID do projeto do Google Cloud .
  • RESPONSE_ID: o ID da resposta a ser excluída.

Método HTTP e URL:

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

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

curl

Execute o seguinte comando:

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses/RESPONSE_ID"

PowerShell

Execute o seguinte comando:

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

Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses/RESPONSE_ID" | Select-Object -Expand Content

O exemplo a seguir mostra uma solicitação curl completa:

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses/5f76a045-71d9-45af-8b07-1f2feae0675a"

Exemplo de resposta:

{
  "deleted": true,
  "id": "5f76a045-71d9-45af-8b07-1f2feae0675a",
  "object": "response"
}

A seguir