Call Responses API

מודלים של Grok מבית XAI ב-Gemini Enterprise Agent Platform תומכים ב-Responses API ליצירת תשובות.

בדף הזה מוסבר איך לבצע קריאות למודלים של Grok באמצעות Responses API.

לפני שמתחילים

כדי להשתמש במודלים של Grok עם Gemini Enterprise Agent Platform, צריך לבצע את השלבים הבאים. צריך להפעיל את Gemini Enterprise Agent Platform API‏ (aiplatform.googleapis.com).

נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

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

Verify that billing is enabled for your Google Cloud project.

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

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

Verify that billing is enabled for your Google Cloud project.

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

הערה: הגדרת store ל-true והפרמטר previous_response_id לקריאות ל-API עם שמירת מצב לא נתמכות כרגע במודלים של Grok, והערך של store הוא false כברירת מחדל. אנחנו מתכננים להוסיף תמיכה בגרסה עתידית. אחרי שנוסיף תמיכה, התנהגות ברירת המחדל תשתנה ל-store: true, וההגדרה previous_response_id תופעל. אם רוצים למנוע את השמירה של התשובות אחרי השינוי הזה, צריך להגדיר במפורש את store לערך false (או False ב-Python) בבקשות.

ביצוע קריאה לא מבוססת-סטרימינג ל-Responses API

בדוגמאות הבאות אפשר לראות איך לשלוח קריאה ל-API של התשובות בלי סטרימינג:

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonההוראות להגדרה במאמר מדריך למתחילים של Agent Platform באמצעות ספריות לקוח.

כדי לבצע אימות ב-Agent Platform, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

לפני שמריצים את הדוגמה הזו, צריך להגדיר את משתנה הסביבה OPENAI_BASE_URL או להגדיר פרטי כניסה של OAuth. למידע נוסף, ראו אימות ופרטי כניסה.

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: שם המודל שרוצים להשתמש בו, לדוגמה xai/grok-4.20-reasoning.
• ‫INPUT: ההנחיה או הקלט למודל.
• ‫MAX_OUTPUT_TOKENS: מספר האסימונים המקסימלי שאפשר ליצור בתגובה. אסימון הוא בערך ארבעה תווים. 100 אסימונים מקבילים בערך ל-60-80 מילים.

  כדי לקבל תשובות קצרות יותר, מציינים ערך נמוך יותר, וכדי לקבל תשובות ארוכות יותר, מציינים ערך גבוה יותר.

REST

אחרי שמגדירים את הסביבה, אפשר להשתמש ב-REST כדי לבדוק הנחייה טקסטואלית. הדוגמה הבאה שולחת בקשה לנקודת הקצה של מודל בעל התוכן הדיגיטלי.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• PROJECT_ID: מזהה הפרויקט ב-Google Cloud.
• ‫MODEL: שם המודל שרוצים להשתמש בו, לדוגמה xai/grok-4.20-reasoning.
• ‫INPUT: ההנחיה או הקלט למודל.
• ‫MAX_OUTPUT_TOKENS: מספר האסימונים המקסימלי שאפשר ליצור בתגובה. אסימון הוא בערך ארבעה תווים. 100 אסימונים מקבילים בערך ל-60-80 מילים.

  כדי לקבל תשובות קצרות יותר, מציינים ערך נמוך יותר, וכדי לקבל תשובות ארוכות יותר, מציינים ערך גבוה יותר.

ה-method של ה-HTTP וכתובת ה-URL:

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

גוף בקשת JSON:

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

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

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

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$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

בדוגמה הבאה מוצגת בקשת curl מלאה:

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

על סמך ההגדרה של Responses API, תשובה שלא מועברת בסטרימינג תכיל מזהה ייחודי, מטא-נתונים של המודל, נתוני שימוש ומערך פלט שמכיל את הטקסט שנוצר.

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

ביצוע קריאה ל-API של התשובות באמצעות סטרימינג

בדוגמאות הבאות מוצגות שליחות קריאה ל-API של התשובות בסטרימינג:

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonההוראות להגדרה במאמר מדריך למתחילים של Agent Platform באמצעות ספריות לקוח.

כדי לבצע אימות ב-Agent Platform, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

לפני שמריצים את הדוגמה הזו, צריך להגדיר את משתנה הסביבה OPENAI_BASE_URL או להגדיר פרטי כניסה של OAuth. למידע נוסף, ראו אימות ופרטי כניסה.

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: שם המודל שרוצים להשתמש בו, לדוגמה xai/grok-4.20-reasoning.
• ‫INPUT: ההנחיה או הקלט למודל.
• ‫MAX_OUTPUT_TOKENS: מספר האסימונים המקסימלי שאפשר ליצור בתגובה. אסימון הוא בערך ארבעה תווים. 100 אסימונים מקבילים בערך ל-60-80 מילים.

  כדי לקבל תשובות קצרות יותר, מציינים ערך נמוך יותר, וכדי לקבל תשובות ארוכות יותר, מציינים ערך גבוה יותר.

REST

אחרי שמגדירים את הסביבה, אפשר להשתמש ב-REST כדי לבדוק הנחייה טקסטואלית. הדוגמה הבאה שולחת בקשה לנקודת הקצה של מודל בעל התוכן הדיגיטלי.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• PROJECT_ID: מזהה הפרויקט ב-Google Cloud.
• ‫MODEL: שם המודל שרוצים להשתמש בו, לדוגמה xai/grok-4.20-reasoning.
• ‫INPUT: ההנחיה או הקלט למודל.
• ‫MAX_OUTPUT_TOKENS: מספר האסימונים המקסימלי שאפשר ליצור בתגובה. אסימון הוא בערך ארבעה תווים. 100 אסימונים מקבילים בערך ל-60-80 מילים.

  כדי לקבל תשובות קצרות יותר, מציינים ערך נמוך יותר, וכדי לקבל תשובות ארוכות יותר, מציינים ערך גבוה יותר.

ה-method של ה-HTTP וכתובת ה-URL:

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

גוף בקשת JSON:

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

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

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

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$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

 

המאמרים הבאים

• מידע נוסף על מודלים של Grok
• איך משתמשים בבקשות להפעלת פונקציות עם Responses API
• איך משתמשים ב-API של התשובות כדי ליצור פלט מובנה.