推理 API
聊天
POST /v1/chat/completions
/v1/chat/completions
根据文本或图像聊天提示创建聊天响应。这是向聊天和图像理解模型发出请求的端点。
请求体
响应体
choicesarray<object>(array<object>,必填)— 模型返回的响应选项列表。长度对应请求体中的 `n`(默认为 1)。
createdinteger(integer,必填)— 聊天补全创建时间的 Unix 时间戳。
idstring(string, required)— 聊天响应的唯一 ID。
modelstring(string,必填)— 用于创建聊天补全的模型 ID。
objectstring(string, required)— 对象类型,始终为 `"chat.completion"`。
service_tier"default" | "priority"("default" | "priority", required)— 请求的处理层。确定调度优先级和计费。
{
"messages": [
{
"role": "system",
"content": "You are a helpful assistant that can answer questions and help with tasks."
},
{
"role": "user",
"content": "What is 101*3?"
}
],
"model": "latest"
}POST /v1/responses
/v1/responses
根据文本或图像 prompt 生成响应。响应 ID 可用于稍后检索该响应,或在不重复此前上下文的情况下继续对话。新响应会保存 30 天,之后永久删除。
请求体
inputstring | array<object | object | object | object | object>(string | array<object | object | object | object | object>, required)— 传递给 `/v1/response` 请求的输入内容。
响应体
backgroundboolean(boolean, required)— OpenResponses 兼容性字段。 暂时没有使用。只是为了 OpenResponses 兼容性。 是否在后台异步处理响应。
created_atinteger(integer, required)— 响应创建时间的 Unix 时间戳(以秒为单位)。
frequency_penaltynumber(number,必填)— Responses API 不支持。正值会根据新 token 在当前文本中的出现频率施加惩罚,从而降低模型逐字重复同一行的可能性。
idstring(string, required)— 响应的唯一 ID。
metadataobject(object, required)— 仅出于兼容性目的而包含。
modelstring(string,必填)— 用于生成响应的模型名称。
objectstring(string, required)— 该资源的对象类型。始终设置为 `response`。
outputarray<object | object | object | object | object | object | object | object | object | object>(array<object | object | object | object | object | object | object | object | object | object>,必填)— 模型生成的响应。
parallel_tool_callsboolean(boolean,必填)— 是否允许模型发起并行工具调用。
presence_penaltynumber(number,必填)— Responses API 不支持。正值会根据新 token 是否已出现在当前文本中施加惩罚,从而提高模型谈论新主题的可能性。
service_tier"default" | "priority"statusstring(string, required)— 响应的状态。 `completed`、`in_progress` 或 `incomplete` 之一。
storeboolean(boolean,必填)— 是否存储输入消息和模型响应以便稍后检索。
textobjecttool_choicestring | object(string | object,必填)— 用于控制模型如何选择工具的参数。
toolsarray<object | object | object | object | object | object | object | object>(array<object | object | object | object | object | object | object | object>,必填)— 模型可按 JSON Schema 调用的工具列表。目前仅支持函数和网页搜索工具,最多支持 128 个工具。
top_logprobsinteger(integer,必填)— 介于 0 和 8 之间的整数,指定每个 token 位置返回的最可能 token 数。
truncationstring(string,必填)— 用于模型响应的截断策略。
代码示例
**响应示例:**
curl -s https://api.x.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $XAI_API_KEY" \
-d '{
"model": "grok-4.6",
"input": "What is the meaning of life?"
}'POST /v1/responses/compact
/v1/responses/compact
将完整的 Responses API 输入窗口压缩为较短的规范窗口。
请求体
inputstring | array<object | object | object | object | object>(string | array<object | object | object | object | object>, required)— 传递给 `/v1/response` 请求的输入内容。
modelstring(string,必填)— 用于压缩摘要的模型。
响应体
created_atinteger(integer, required)— 创建压缩对话时的 Unix 时间戳(以秒为单位)。
idstring(string, required)— 此压缩的唯一 ID(例如 `cmp_<uuid>`)。
modelstring(string,必填)— 用于压缩摘要的模型。
objectstring(string, required)— 始终为 `"response.compaction"`。
outputarray<object | object | object | object | object>(array<object | object | object | object | object>, required)— 包含单个压缩项的压缩输出。 将此逐字作为输入传递给下一个 `/v1/responses` 调用。
代码示例
**响应示例:**
curl -s https://api.x.ai/v1/responses/compact \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $XAI_API_KEY" \
-d '{
"model": "grok-4.6",
"input": [
{"role": "system", "content": "You are a concise and knowledgeable science tutor."},
{"role": "user", "content": "What is the Higgs boson and why is it important?"},
{"role": "assistant", "content": "The Higgs boson is an elementary particle in the Standard Model, predicted by Peter Higgs in 1964 and confirmed at CERN in 2012. It is the quantum excitation of the Higgs field, which gives mass to fundamental particles via the Higgs mechanism."},
{"role": "user", "content": "How does the Higgs mechanism actually work?"},
{"role": "assistant", "content": "Through spontaneous symmetry breaking. The Higgs field has a nonzero vacuum value, and particles acquire mass in proportion to how strongly they couple to it. Photons do not couple, which is why they remain massless."}
]
}'GET /v1/responses/{response_id}
/v1/responses/{response_id}
检索之前生成的响应。
路径参数
response_idstring(string, required)— 先前创建响应请求返回的响应 ID。
响应体
backgroundboolean(boolean, required)— OpenResponses 兼容性字段。 暂时没有使用。只是为了 OpenResponses 兼容性。 是否在后台异步处理响应。
created_atinteger(integer, required)— 响应创建时间的 Unix 时间戳(以秒为单位)。
frequency_penaltynumber(number,必填)— Responses API 不支持。正值会根据新 token 在当前文本中的出现频率施加惩罚,从而降低模型逐字重复同一行的可能性。
idstring(string, required)— 响应的唯一 ID。
metadataobject(object, required)— 仅出于兼容性目的而包含。
modelstring(string,必填)— 用于生成响应的模型名称。
objectstring(string, required)— 该资源的对象类型。始终设置为 `response`。
outputarray<object | object | object | object | object | object | object | object | object | object>(array<object | object | object | object | object | object | object | object | object | object>,必填)— 模型生成的响应。
parallel_tool_callsboolean(boolean,必填)— 是否允许模型发起并行工具调用。
presence_penaltynumber(number,必填)— Responses API 不支持。正值会根据新 token 是否已出现在当前文本中施加惩罚,从而提高模型谈论新主题的可能性。
service_tier"default" | "priority"statusstring(string, required)— 响应的状态。 `completed`、`in_progress` 或 `incomplete` 之一。
storeboolean(boolean,必填)— 是否存储输入消息和模型响应以便稍后检索。
textobjecttool_choicestring | object(string | object,必填)— 用于控制模型如何选择工具的参数。
toolsarray<object | object | object | object | object | object | object | object>(array<object | object | object | object | object | object | object | object>,必填)— 模型可按 JSON Schema 调用的工具列表。目前仅支持函数和网页搜索工具,最多支持 128 个工具。
top_logprobsinteger(integer,必填)— 介于 0 和 8 之间的整数,指定每个 token 位置返回的最可能 token 数。
truncationstring(string,必填)— 用于模型响应的截断策略。
{
"created_at": 1754475266,
"id": "ad5663da-63e6-86c6-e0be-ff15effa8357",
"max_output_tokens": null,
"model": "latest",
"object": "response",
"output": [
{
"content": [
{
"type": "output_text",
"text": "101 multiplied by 3 is 303.",
"logprobs": null,
"annotations": []
}
],
"id": "msg_ad5663da-63e6-86c6-e0be-ff15effa8357",
"role": "assistant",
"type": "message",
"status": "completed"
},
{
"id": "",
"summary": [
{
"text": "First, the user asked: \"What is 101*3?\"\n\nThis is a simple multiplication: 101 multiplied by 3.\n\nCalculating: 100 * 3 = 300, and 1 * 3 = 3, so 300 + 3 = 303.\n\nI should respond helpfully and directly, as per my system prompt: \"You are a helpful assistant that can answer questions and help with tasks.\"\n\nKeep the response concise and accurate. No need for extra fluff unless it adds value.\n\nFinal answer: 303.",
"type": "summary_text"
}
],
"type": "reasoning",
"status": "completed"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": null,
"temperature": null,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": null,
"usage": {
"prompt_tokens": 32,
"completion_tokens": 9,
"total_tokens": 151,
"prompt_tokens_details": {
"text_tokens": 32,
"audio_tokens": 0,
"image_tokens": 0,
"cached_tokens": 8
},
"completion_tokens_details": {
"reasoning_tokens": 110,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
},
"num_sources_used": 0
},
"user": null,
"incomplete_details": null,
"status": "completed",
"store": true
}DELETE /v1/responses/{response_id}
/v1/responses/{response_id}
删除之前生成的响应。
路径参数
response_idstring(string, required)— 先前创建响应请求返回的响应 ID。
响应体
deletedboolean(boolean, required)— 响应是否已成功删除。
idstring(string,必填)— 要删除的 response_id。
objectstring(string, required)— 已删除的对象类型,始终为 `response`。
{
"id": "ad5663da-63e6-86c6-e0be-ff15effa8357",
"object": "response",
"deleted": true
}GET /v1/chat/deferred-completion/{request_id}
/v1/chat/deferred-completion/{request_id}
尝试获取先前开始的延迟完成的结果。如果请求已完成,则返回 `200 Success` 和响应正文。当请求正在等待处理时,返回 `202 Accepted`。
路径参数
request_idstring(string, required)— 先前的延迟聊天请求返回的延迟请求 ID。
响应体
choicesarray<object>(array<object>,必填)— 模型返回的响应选项列表。长度对应请求体中的 `n`(默认为 1)。
createdinteger(integer,必填)— 聊天补全创建时间的 Unix 时间戳。
idstring(string, required)— 聊天响应的唯一 ID。
modelstring(string,必填)— 用于创建聊天补全的模型 ID。
objectstring(string, required)— 对象类型,始终为 `"chat.completion"`。
service_tier"default" | "priority"("default" | "priority", required)— 请求的处理层。确定调度优先级和计费。
{
"id": "335b92e4-afa5-48e7-b99c-b9a4eabc1c8e",
"object": "chat.completion",
"created": 1743770624,
"model": "latest",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "101 multiplied by 3 is 303.",
"refusal": null
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 31,
"completion_tokens": 11,
"total_tokens": 42,
"prompt_tokens_details": {
"text_tokens": 31,
"audio_tokens": 0,
"image_tokens": 0,
"cached_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"system_fingerprint": "fp_156d35dcaa"
}最后更新:2026 年 5 月 21 日