API Call Responses

Les modèles Grok de xAI sur Gemini Enterprise Agent Platform sont compatibles avec l'API Responses pour générer des réponses.

Cette page explique comment appeler des modèles Grok à l'aide de l'API Responses.

Avant de commencer

Pour utiliser des modèles Grok avec Gemini Enterprise Agent Platform, procédez comme suit. L'API Gemini Enterprise Agent Platform (aiplatform.googleapis.com) doit être activée.

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.
  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

Effectuer un appel sans état à l'API Responses

La valeur par défaut de store est false. Les requêtes sont donc sans état, sauf si vous définissez store sur true. Les exemples suivants définissent explicitement store sur false (ou False en Python).

Effectuer un appel sans streaming à l'API Responses

Les exemples suivants montrent comment effectuer un appel sans flux vers l'API Responses :

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide d'Agent Platform à l'aide des bibliothèques clientes.

Pour vous authentifier auprès d'Agent Platform, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

Avant d'exécuter cet exemple, veillez à définir la variable d'environnement OPENAI_BASE_URL ou à configurer les identifiants OAuth. Pour en savoir plus, consultez Authentification et identifiants.

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 : ID de votre projet Google Cloud .
  • MODEL : nom du modèle que vous souhaitez utiliser, par exemple xai/grok-4.7.
  • INPUT : prompt ou entrée pour le modèle.
  • MAX_OUTPUT_TOKENS : le nombre maximal de jetons pouvant être générés dans la réponse. Un jeton correspond environ à quatre caractères. 100 jetons correspondent à environ 60-80 mots.

    Spécifiez une valeur inférieure pour obtenir des réponses plus courtes et une valeur supérieure pour des réponses potentiellement plus longues.

REST

Une fois que vous avez configuré votre environnement, vous pouvez utiliser REST pour tester un prompt textuel. L'exemple suivant envoie une requête au point de terminaison du modèle de l'éditeur.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • MODEL : nom du modèle que vous souhaitez utiliser, par exemple xai/grok-4.7.
  • INPUT : prompt ou entrée pour le modèle.
  • MAX_OUTPUT_TOKENS : le nombre maximal de jetons pouvant être générés dans la réponse. Un jeton correspond environ à quatre caractères. 100 jetons correspondent à environ 60-80 mots.

    Spécifiez une valeur inférieure pour obtenir des réponses plus courtes et une valeur supérieure pour des réponses potentiellement plus longues.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

L'exemple suivant montre une requête curl complète :

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
  }'

D'après la définition de l'API Responses, une réponse sans streaming contient un identifiant unique, des métadonnées de modèle, des statistiques d'utilisation et un tableau de sortie contenant le texte généré.

{
  "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
}

Effectuer un appel en flux continu à l'API Responses

Les exemples suivants montrent comment effectuer un appel en flux continu à l'API Responses :

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide d'Agent Platform à l'aide des bibliothèques clientes.

Pour vous authentifier auprès d'Agent Platform, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

Avant d'exécuter cet exemple, veillez à définir la variable d'environnement OPENAI_BASE_URL ou à configurer les identifiants OAuth. Pour en savoir plus, consultez Authentification et identifiants.

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 : ID de votre projet Google Cloud .
  • MODEL : nom du modèle que vous souhaitez utiliser, par exemple xai/grok-4.7.
  • INPUT : prompt ou entrée pour le modèle.
  • MAX_OUTPUT_TOKENS : le nombre maximal de jetons pouvant être générés dans la réponse. Un jeton correspond environ à quatre caractères. 100 jetons correspondent à environ 60-80 mots.

    Spécifiez une valeur inférieure pour obtenir des réponses plus courtes et une valeur supérieure pour des réponses potentiellement plus longues.

REST

Une fois que vous avez configuré votre environnement, vous pouvez utiliser REST pour tester un prompt textuel. L'exemple suivant envoie une requête au point de terminaison du modèle de l'éditeur.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • MODEL : nom du modèle que vous souhaitez utiliser, par exemple xai/grok-4.7.
  • INPUT : prompt ou entrée pour le modèle.
  • MAX_OUTPUT_TOKENS : le nombre maximal de jetons pouvant être générés dans la réponse. Un jeton correspond environ à quatre caractères. 100 jetons correspondent à environ 60-80 mots.

    Spécifiez une valeur inférieure pour obtenir des réponses plus courtes et une valeur supérieure pour des réponses potentiellement plus longues.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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
 

Effectuer un appel avec état à l'API Responses

Pour effectuer des requêtes avec état, vous devez configurer votre service de règles d'administration pour les autoriser. Plus précisément, mettez à jour la contrainte constraints/vertexai.allowedPartnerModelFeatures en ajoutant publishers/xai/models/MODEL_NAME:stateful_responses_api aux valeurs autorisées (par exemple, publishers/xai/models/grok-4.7:stateful_responses_api). Pour en savoir plus, consultez Contrôler l'accès au modèle.

L'API Responses est compatible avec les conversations multitours via des requêtes avec état. La valeur par défaut de store est false. Par conséquent, pour effectuer une requête avec état, vous devez définir explicitement store sur true. Dans une conversation avec état, vous pouvez référencer une réponse précédente en fournissant son id dans le champ previous_response_id.

Créer une réponse

Les exemples suivants montrent une conversation à deux tours à l'aide de l'API Responses :

Tour 1 : Requête initiale

Lors du premier tour, effectuez une requête avec store défini sur true. Si vous omettez le paramètre store, il est défini par défaut sur false et la réponse n'est pas stockée.

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide d'Agent Platform à l'aide des bibliothèques clientes.

Pour vous authentifier auprès d'Agent Platform, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

Avant d'exécuter cet exemple, veillez à définir la variable d'environnement OPENAI_BASE_URL ou à configurer les identifiants OAuth. Pour en savoir plus, consultez Authentification et identifiants.

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 : ID de votre projet Google Cloud .
  • MODEL : nom du modèle que vous souhaitez utiliser, par exemple xai/grok-4.7.

Exemple de réponse pour le tour 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

Une fois que vous avez configuré votre environnement, vous pouvez utiliser REST pour tester un prompt textuel. L'exemple suivant envoie une requête au point de terminaison du modèle de l'éditeur.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • MODEL : nom du modèle que vous souhaitez utiliser, par exemple xai/grok-4.7.

Méthode HTTP et URL :

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

Corps JSON de la requête :

{
  "model": "MODEL",
  "input": "randomly pick 3 colors, just return the words of the colors",
  "store": true
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

L'exemple suivant montre une requête curl complète :

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
  }'

Exemple de réponse pour le tour 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
}

Tour 2 : Demande de suivi

Dans le deuxième tour, référencez l'ID de la réponse précédente dans le paramètre previous_response_id. Définissez store sur true si vous souhaitez également stocker cette réponse, par exemple pour poursuivre la conversation ou la récupérer ultérieurement.

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide d'Agent Platform à l'aide des bibliothèques clientes.

Pour vous authentifier auprès d'Agent Platform, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

Avant d'exécuter cet exemple, veillez à définir la variable d'environnement OPENAI_BASE_URL ou à configurer les identifiants OAuth. Pour en savoir plus, consultez Authentification et identifiants.

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 : ID de votre projet Google Cloud .
  • MODEL : nom du modèle que vous souhaitez utiliser, par exemple xai/grok-4.7.
  • PREVIOUS_RESPONSE_ID : ID de la réponse précédente pour poursuivre la conversation.

Exemple de réponse pour le tour 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

Une fois que vous avez configuré votre environnement, vous pouvez utiliser REST pour tester un prompt textuel. L'exemple suivant envoie une requête au point de terminaison du modèle de l'éditeur.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • MODEL : nom du modèle que vous souhaitez utiliser, par exemple xai/grok-4.7.
  • PREVIOUS_RESPONSE_ID : ID de la réponse précédente.

Méthode HTTP et URL :

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

Corps JSON de la requête :

{
  "model": "MODEL",
  "input": "What is the second color?",
  "previous_response_id": "PREVIOUS_RESPONSE_ID",
  "store": true
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

L'exemple suivant montre une requête curl complète :

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
  }'

Exemple de réponse pour le tour 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
}

Obtenir une réponse

Vous pouvez récupérer une réponse générée précédemment à l'aide de son ID.

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide d'Agent Platform à l'aide des bibliothèques clientes.

Pour vous authentifier auprès d'Agent Platform, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

Avant d'exécuter cet exemple, veillez à définir la variable d'environnement OPENAI_BASE_URL ou à configurer les identifiants OAuth. Pour en savoir plus, consultez Authentification et identifiants.

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 : ID de votre projet Google Cloud .
  • RESPONSE_ID : ID de la réponse à récupérer.

Exemple de réponse :

{
  "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

Une fois que vous avez configuré votre environnement, vous pouvez utiliser REST pour tester un prompt textuel. L'exemple suivant envoie une requête au point de terminaison du modèle de l'éditeur.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • RESPONSE_ID : ID de la réponse à récupérer.

Méthode HTTP et URL :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

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

Exécutez la commande suivante :

$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

L'exemple suivant montre une requête curl complète :

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"

Exemple de réponse :

{
  "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
}

Supprimer une réponse

Vous pouvez supprimer une réponse générée précédemment à l'aide de son ID.

Une fois que vous avez supprimé une réponse, vous ne pouvez pas la récupérer ni utiliser son ID comme previous_response_id dans une nouvelle requête. La suppression d'une réponse ne supprime pas son contenu des réponses ultérieures de la même conversation : chaque réponse qui la référence via previous_response_id conserve ce contenu comme contexte jusqu'à ce que vous supprimiez également cette réponse. Pour supprimer une conversation entière, supprimez toutes les réponses qu'elle contient.

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide d'Agent Platform à l'aide des bibliothèques clientes.

Pour vous authentifier auprès d'Agent Platform, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

Avant d'exécuter cet exemple, veillez à définir la variable d'environnement OPENAI_BASE_URL ou à configurer les identifiants OAuth. Pour en savoir plus, consultez Authentification et identifiants.

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 : ID de votre projet Google Cloud .
  • RESPONSE_ID : ID de la réponse à supprimer.

Exemple de réponse :

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

REST

Une fois que vous avez configuré votre environnement, vous pouvez utiliser REST pour tester un prompt textuel. L'exemple suivant envoie une requête au point de terminaison du modèle de l'éditeur.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • RESPONSE_ID : ID de la réponse à supprimer.

Méthode HTTP et URL :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

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

Exécutez la commande suivante :

$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

L'exemple suivant montre une requête curl complète :

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"

Exemple de réponse :

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

Étapes suivantes