xAI 文档

外观

模型能力 ​

生成文本 ​

Responses API 是通过 API 与我们的模型交互的首选方式。它允许与我们的模型进行可选的有状态交互，其中先前的输入提示、推理内容和模型响应被保存在 xAI 的服务器上。您可以通过附加新的提示消息来继续交互，而不是重新发送整个对话。此行为默认开启。如果您想在本地存储请求/响应，请参阅禁用在服务器上存储先前的请求/响应。

响应将被存储30天，之后将被删除。这意味着您可以在发送请求后的30天内使用响应 ID 来检索或继续对话。 如果您想在30天后继续对话，请将您的响应历史记录和加密的思考内容存储在本地，并在新的请求体中传递它们。

对于 Python，我们还提供 xAI SDK，它涵盖了我们的所有功能，并使用 gRPC 以获得最佳性能。两者混合使用没有问题。xAI SDK 允许您与我们的所有产品（如 Collections、Voice API、API 密钥管理等）进行交互，而 Responses API 更适合聊天机器人和在 RESTful API 中使用。

先决条件 ​

在 xAI Console API Keys 页面 创建一个 API 密钥。在您的环境中设置 API 密钥：

bash
export XAI_API_KEY="your_api_key"

创建新的模型响应 ​

首先创建一个响应：

python
import os
from xai_sdk import Client
from xai_sdk.chat import user, system

client = Client(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
    timeout=3600,
)

chat = client.chat.create(model="grok-4.5")
chat.append(system("You are Grok, an AI agent built to answer helpful questions."))
chat.append(user("How big is the universe?"))
response = chat.sample()

print(response)

# The response ID that can be used to continue the conversation later

print(response.id)
python
import os
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_XAI_API_KEY_HERE>",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0), # Override default timeout with longer timeout for reasoning models
)

response = client.responses.create(
    model="grok-4.5",
    input=[
        {"role": "system", "content": "You are Grok, an AI agent built to answer helpful questions."},
        {"role": "user", "content": "How big is the universe?"},
    ],
)

print(response)

# The response ID that can be used to continue the conversation later

print(response.id)
javascript
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "<api key>",
    baseURL: "https://api.x.ai/v1",
    timeout: 360000, // Override default timeout with longer timeout for reasoning models
});

const response = await client.responses.create({
    model: "grok-4.5",
    input: [
        {
            role: "system",
            content: "You are Grok, an AI agent built to answer helpful questions."
        },
        {
            role: "user",
            content: "How big is the universe?"
        },
    ],
});

console.log(response);

// The response ID that can be used to recall the conversation later
console.log(response.id);
javascript
import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text, response } = await generateText({
  model: xai.responses('grok-4.5'),
  system: "You are Grok, an AI agent built to answer helpful questions.",
  prompt: "How big is the universe?",
});

console.log(text);

// The response ID can be used to continue the conversation
console.log(response.id);
bash
curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -m 3600 \
  -d '{
    "model": "grok-4.5",
    "input": [
        {
            "role": "system",
            "content": "You are Grok, an AI agent built to answer helpful questions."
        },
        {
            "role": "user",
            "content": "How big is the universe?"
        }
    ]
}'

禁用在服务器上存储先前的请求/响应 ​

如果您不想在服务器上存储先前的请求/响应，可以在请求中设置 store: false。

python
import os
from xai_sdk import Client
from xai_sdk.chat import user, system

client = Client(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
    timeout=3600,
)

chat = client.chat.create(model="grok-4.5", store_messages=False)
chat.append(system("You are Grok, an AI agent built to answer helpful questions."))
chat.append(user("How big is the universe?"))
response = chat.sample()

print(response)
python
import os
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_XAI_API_KEY_HERE>",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0), # Override default timeout with longer timeout for reasoning models
)

response = client.responses.create(
    model="grok-4.5",
    input=[
        {"role": "system", "content": "You are Grok, an AI agent built to answer helpful questions."},
        {"role": "user", "content": "How big is the universe?"},
    ],
    store=False
)

print(response)
javascript
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "<api key>",
    baseURL: "https://api.x.ai/v1",
    timeout: 360000, // Override default timeout with longer timeout for reasoning models
});

const response = await client.responses.create({
    model: "grok-4.5",
    input: [
        {
            role: "system",
            content: "You are Grok, an AI agent built to answer helpful questions."
        },
        {
            role: "user",
            content: "How big is the universe?"
        },
    ],
    store: false
});

console.log(response);
bash
curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -m 3600 \
  -d '{
    "model": "grok-4.5",
    "input": [
        {
            "role": "system",
            "content": "You are Grok, an AI agent built to answer helpful questions."
        },
        {
            "role": "user",
            "content": "How big is the universe?"
        }
    ],
    "store": false
}'

返回加密的思考内容 ​

如果您想返回加密的思考痕迹，需要在 xAI SDK 或 gRPC 请求消息中指定 use_encrypted_content=True，或者在请求体中指定 include: ["reasoning.encrypted_content"]。

NOTE

使用加密的思考内容时，请确保使用推理模型。

修改创建聊天客户端（xAI SDK）的步骤或按如下方式更改请求体：

python
chat = client.chat.create(model="grok-4.5",
        use_encrypted_content=True)
python
response = client.responses.create(
    model="grok-4.5",
    input=[
        {"role": "system", "content": "You are Grok, an AI agent built to answer helpful questions."},
        {"role": "user", "content": "How big is the universe?"},
    ],
    include=["reasoning.encrypted_content"]
)
javascript
const response = await client.responses.create({
    model: "grok-4.5",
    input: [
        {"role": "system", "content": "You are Grok, an AI agent built to answer helpful questions."},
        {"role": "user", "content": "How big is the universe?"},
    ],
    include: ["reasoning.encrypted_content"],
});
javascript
import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

// Encrypted reasoning content is included automatically by the AI SDK
// as long as `store: false` is not set. No extra configuration is needed.
const { text, reasoning } = await generateText({
  model: xai.responses('grok-4.5'),
  system: "You are Grok, an AI agent built to answer helpful questions.",
  prompt: "How big is the universe?",
});

console.log(text);
console.log(reasoning); // Contains encrypted reasoning content
bash
curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -m 3600 \
  -d '{
    "model": "grok-4.5",
    "input": [
        {
            "role": "system",
            "content": "You are Grok, an AI agent built to answer helpful questions."
        },
        {
            "role": "user",
            "content": "How big is the universe?"
        }
    ],
    "include": ["reasoning.encrypted_content"]
}'

有关在发出新请求时如何使用返回的加密思考内容，请参阅添加加密思考内容。

链接对话 ​

我们现在有了第一个响应的 id。使用 Chat Completions API 时，我们通常发送一个包含所有先前消息的无状态新请求。

使用 Responses API，我们可以发送先前响应的 id，以及要附加的新消息。

python
import os
from xai_sdk import Client
from xai_sdk.chat import user, system

client = Client(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
    timeout=3600,
)

chat = client.chat.create(model="grok-4.5", store_messages=True)
chat.append(system("You are Grok, an AI agent built to answer helpful questions."))
chat.append(user("How big is the universe?"))
response = chat.sample()

print(response)

# The response ID that can be used to continue the conversation later

print(response.id)

# New steps

chat = client.chat.create(
    model="grok-4.5",
    previous_response_id=response.id,
    store_messages=True,
)
chat.append(user("How do stars form?"))
second_response = chat.sample()

print(second_response)

# The response ID that can be used to continue the conversation later

print(second_response.id)
python
# Previous steps
import os
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_XAI_API_KEY_HERE>",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0), # Override default timeout with longer timeout for reasoning models
)

response = client.responses.create(
    model="grok-4.5",
    input=[
        {"role": "system", "content": "You are Grok, an AI agent built to answer helpful questions."},
        {"role": "user", "content": "How big is the universe?"},
    ],
)

print(response)

# The response ID that can be used to continue the conversation later

print(response.id)

# New steps

second_response = client.responses.create(
    model="grok-4.5",
    previous_response_id=response.id,
    input=[
        {"role": "user", "content": "How do stars form?"},
    ],
)

print(second_response)

# The response ID that can be used to continue the conversation later

print(second_response.id)
javascript
// Previous steps
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "<api key>",
    baseURL: "https://api.x.ai/v1",
    timeout: 360000, // Override default timeout with longer timeout for reasoning models
});

const response = await client.responses.create({
    model: "grok-4.5",
    input: [
        {
            role: "system",
            content: "You are Grok, an AI agent built to answer helpful questions."
        },
        {
            role: "user",
            content: "How big is the universe?"
        },
    ],
});

console.log(response);

// The response ID that can be used to recall the conversation later
console.log(response.id);

const secondResponse = await client.responses.create({
    model: "grok-4.5",
    previous_response_id: response.id,
    input: [
        {"role": "user", "content": "How do stars form?"},
    ],
});

console.log(secondResponse);

// The response ID that can be used to recall the conversation later
console.log(secondResponse.id);
javascript
import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

// First request
const result = await generateText({
  model: xai.responses('grok-4.5'),
  system: "You are Grok, an AI agent built to answer helpful questions.",
  prompt: "How big is the universe?",
});

console.log(result.text);

// Get the response ID from the response object
const responseId = result.response.id;

// Continue the conversation using previousResponseId
const { text: secondResponse } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: "How do stars form?",
  providerOptions: {
    xai: {
      previousResponseId: responseId,
    },
  },
});

console.log(secondResponse);
bash
curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -m 3600 \
  -d '{
    "model": "grok-4.5",
    "previous_response_id": "The previous response ID",
    "input": [
        {
            "role": "user",
            "content": "How do stars form?"
        }
    ]
}'

添加加密思考内容 ​

返回加密的思考内容后，您也可以将其添加到新响应的输入中。

NOTE

使用加密的思考内容时，请确保使用推理模型。

python
import os
from xai_sdk import Client
from xai_sdk.chat import user, system

client = Client(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
    timeout=3600,
)

chat = client.chat.create(model="grok-4.5", store_messages=True, use_encrypted_content=True)
chat.append(system("You are Grok, an AI agent built to answer helpful questions."))
chat.append(user("How big is the universe?"))
response = chat.sample()

print(response)

# The response ID that can be used to continue the conversation later

print(response.id)

# New steps

chat.append(response)  ## Append the response and the SDK will automatically add the outputs from response to message history

chat.append(user("How do stars form?"))
second_response = chat.sample()

print(second_response)

# The response ID that can be used to continue the conversation later

print(second_response.id)
python
# Previous steps
import os
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_XAI_API_KEY_HERE>",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0), # Override default timeout with longer timeout for reasoning models
)

response = client.responses.create(
    model="grok-4.5",
    input=[
        {"role": "system", "content": "You are Grok, an AI agent built to answer helpful questions."},
        {"role": "user", "content": "How big is the universe?"},
    ],
    include=["reasoning.encrypted_content"]
)

print(response)

# The response ID that can be used to continue the conversation later

print(response.id)

# New steps

second_response = client.responses.create(
    model="grok-4.5",
    input=[
        *response.output,  # Use response.output instead of the stored response
        {"role": "user", "content": "How do stars form?"},
    ],
)

print(second_response)

# The response ID that can be used to continue the conversation later

print(second_response.id)
javascript
// Previous steps
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "<api key>",
    baseURL: "https://api.x.ai/v1",
    timeout: 360000, // Override default timeout with longer timeout for reasoning models
});

const response = await client.responses.create({
    model: "grok-4.5",
    input: [
        {
            role: "system",
            content: "You are Grok, an AI agent built to answer helpful questions."
        },
        {
            role: "user",
            content: "How big is the universe?"
        },
    ],
    include: ["reasoning.encrypted_content"],
});

console.log(response);

// The response ID that can be used to recall the conversation later
console.log(response.id);

const secondResponse = await client.responses.create({
    model: "grok-4.5",
    input: [
        ...response.output,  // Use response.output instead of the stored response
        {"role": "user", "content": "How do stars form?"},
    ],
});

console.log(secondResponse);

// The response ID that can be used to recall the conversation later
console.log(secondResponse.id);
javascript
import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

// First request. Encrypted reasoning content is included automatically
// by the AI SDK as long as `store: false` is not set.
const result = await generateText({
  model: xai.responses('grok-4.5'),
  system: "You are Grok, an AI agent built to answer helpful questions.",
  prompt: "How big is the universe?",
});

console.log(result.text);

// Continue the conversation using previousResponseId
// The encrypted content is automatically included when using previousResponseId
const { text: secondResponse } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: "How do stars form?",
  providerOptions: {
    xai: {
      previousResponseId: result.response.id,
    },
  },
});

console.log(secondResponse);
bash
curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -m 3600 \
  -d '{
    "model": "grok-4.5",
    "input": [
        {
            "role": "system",
            "content": "You are Grok, an AI agent built to answer helpful questions."
        },
        {
            "role": "user",
            "content": "How big is the universe?"
        },
        {
            "id": "rs_51abe1aa-599b-80b6-57c8-dddc6263362f_us-east-1",
            "summary": [],
            "type": "reasoning",
            "status": "completed",
            "encrypted_content": "bvV88j99ILvgfHRTHCUSJtw+ISji6txJzPdZNbcSVuDk4OMG2Z9r5wOBBwjd3u3Hhm9XtpCWJO1YgTOlpgbn+g7DZX+pOagYYrCFUpQ19XkWz6Je8bHG9JcSDoGDqNgRbDbAUO8at6RCyqgPupJj5ArBDCt73fGQLTC4G3S0JMK9LsPiWz6GPj6qyzYoRzkj4R6bntRm74E4h8Y+z6u6B7+ixPSv8s1EFs8c+NUAB8TNKZZpXZquj2LXfx1xAie85Syl7qLqxLNtDG1dNBhBnHpYoE4gQzwyXqywf5pF2Q2imzPNzGQhurK+6gaNWgZbxRmjhdsW6TnzO5Kk6pzb5qpfgfcEScQeYHSj5GpD+yDUCNlhdbzhhWnEErH+wuBPpTG6UQhiC7m7yrJ7IY2E8K/BeUPlUvkhMaMwb4dA279pWMJdchNJ+TAxca+JVc80pXMG/PmrQUNJU9qdXRLbNmQbRadBNwV2qkPfgggL3q0yNd7Un9P+atmP3B9keBILif3ufsBDtVUobEniiyGV7YVDvQ/fQRVs7XDxJiOKkogjjQySyHgpjseO8iG5xtb9mrz6B3mDvv2aAuyDL6MHZRM7QDVPjUbgNMzDm5Sm3J7IhtzfR+3eMDws3qeTsxOt1KOslu983Btv1Wx37b5HJqX1pQU1dae/kOSJ7MifFd6wMkQtQBDgVoG3ka9wq5Vxq9Ki8bDOOMcwA2kUXhCcY3TZCXJfDWSKPTcCoNCYIv5LT2NFVdamiSfLIyeOjBNz459BfMvAoOZShFViQyc5YwjnReUQPQ8a18jcz8GoAK1O99e0h91oYxIgDV52EfS+IYrzqvJOEQbKQinB+LJwkPbBEp7ZtgAtiNBzm985hNgLfiBaVFWcRYwI3tNBCT1vkw2YI0NEEG0yOF29x+u64XzqyP1CX1pU6sGXEFn3RPdfYibf6bt/Y1BRqBL5l0CrXWsgDw02SqIFta8OvJ7Iwmq40/4acE/Ew6eWO/z2MHkWgqSpwGNjn7MfeKkTi44foZjfNqN9QOFQt6VG2tY+biKZDo0h9DAftae8Q2Xs2UDvsBYOm7YEahVkput6/uKzxljpXlz269qHk6ckvdN9hKLbaTO3/IZPCCPQ5a/a/sWn/1VOJj72sDk+23RNjBf0FL6bJMXZI5aQdtxbF1zij9mWcP9nJ9FHhj53ytuf1NiKl5xU8ZsaoKmCAJcXUz1n2FZvyWlqvgPYiszc7R8Y5dF6QbW2mlKnXzVy6qRMHNeQqGhCEncyT5nPNSdK5QlUwLokAIg"
        },
        {
            "content": [
                {
                    "type": "output_text",
                    "text": "42\n\nThis is, of course, the iconic answer from Douglas Adams'\'' *The Hitchhiker'\''s Guide to the Galaxy*, where a supercomputer named Deep Thought spends 7.5 million years computing the \"Answer to the Ultimate Question of Life, the Universe, and Everything\"—only to reveal it'\''s 42. (The real challenge, it turns out, is figuring out what the actual *question* was.)\n\nIf you'\''re asking in a more literal or philosophical sense, the universe doesn'\''t have a single tidy answer—it'\''s full of mysteries like quantum mechanics, dark matter, and why cats knock things off tables. But 42? That'\''s as good a starting point as any. What'\''s your take on it?",
                    "logprobs": null,
                    "annotations": []
                }
            ],
            "id": "msg_c2f68a9b-87cd-4f85-a9e9-b6047213a3ce_us-east-1",
            "role": "assistant",
            "type": "message",
            "status": "completed"
        },
        {
            "role": "user",
            "content": "How do stars form?"
        }
    ],
    "include": [
        "reasoning.encrypted_content"
    ]
}'

检索先前的模型响应 ​

如果您有先前响应的 ID，可以检索响应的内容。

python
import os
from xai_sdk import Client
from xai_sdk.chat import user, system

client = Client(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
    timeout=3600,
)

response = client.chat.get_stored_completion("<The previous response's id>")

print(response)
python
import os
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_XAI_API_KEY_HERE>",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0), # Override default timeout with longer timeout for reasoning models
)

response = client.responses.retrieve("<The previous response's id>")

print(response)
javascript
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "<api key>",
    baseURL: "https://api.x.ai/v1",
    timeout: 360000, // Override default timeout with longer timeout for reasoning models
});

const response = await client.responses.retrieve("<The previous response's id>");

console.log(response);
javascript
// Note: The Vercel AI SDK does not provide a method to retrieve previous responses.
// Use the OpenAI SDK as shown above for this functionality.

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "<api key>",
    baseURL: "https://api.x.ai/v1",
    timeout: 360000,
});

const response = await client.responses.retrieve("<The previous response's id>");

console.log(response);
bash
curl https://api.x.ai/v1/responses/{response_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -m 3600

删除模型响应 ​

如果您不再想存储先前的模型响应，可以将其删除。

python
import os
from xai_sdk import Client
from xai_sdk.chat import user, system

client = Client(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
    timeout=3600,
)

response = client.chat.delete_stored_completion("<The previous response's id>")
print(response)
python
import os
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_XAI_API_KEY_HERE>",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0), # Override default timeout with longer timeout for reasoning models
)

response = client.responses.delete("<The previous response's id>")

print(response)
javascript
import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "<api key>",
    baseURL: "https://api.x.ai/v1",
    timeout: 360000, // Override default timeout with longer timeout for reasoning models
});

const response = await client.responses.delete("<The previous response's id>");

console.log(response);
javascript
// Note: The Vercel AI SDK does not provide a method to delete previous responses.
// Use the OpenAI SDK as shown above for this functionality.

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "<api key>",
    baseURL: "https://api.x.ai/v1",
    timeout: 360000,
});

const response = await client.responses.delete("<The previous response's id>");

console.log(response);
bash
curl -X DELETE https://api.x.ai/v1/responses/{response_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -m 3600

本文档为 docs.x.ai 全站中文翻译，由 AI 自动翻译生成。代码示例请以原文为准。

xAI 文档中文版 · 仅供学习参考