Responses API 是文本生成、推理和工具使用的主要接口。请参阅文本生成指南了解用法。

创建新 response

/v1/responses

根据文本或图像提示生成响应。响应 ID 可用于稍后检索响应，或在不重复先前上下文的情况下继续对话。新响应会保存 30 天，随后永久删除。

请求体

传递给 `/v1/response` 请求的输入内容。

响应体

backgroundboolean

OpenResponses 兼容字段。目前未使用，仅用于 OpenResponses 兼容性。是否在后台异步处理响应。

created_atinteger

响应创建时间的 Unix 时间戳（秒）。

errorobject

模型未能生成响应时返回的错误对象。

frequency_penaltynumber

（Responses API 不支持）正值根据 token 在已有文本中的出现频率惩罚新 token，降低模型逐字重复同一行的可能性。

idstring

响应的唯一 ID。

metadataobject

仅为兼容性而包含。

modelstring

用于生成响应的模型名称。

objectstring

此资源的对象类型，始终为 `response`。

模型生成的响应。

parallel_tool_callsboolean

是否允许模型并行调用工具。

presence_penaltynumber

（Responses API 不支持）正值根据 token 是否已在文本中出现来惩罚新 token，提高模型讨论新话题的可能性。

service_tier"default" | "priority" | "fast"

（"default" | "priority" | "fast"，必填）

statusstring

响应状态，为 `completed`、`in_progress` 或 `incomplete`。

storeboolean

是否保存输入消息和模型响应，供稍后检索。

textobject

tool_choicestring | object

控制模型如何选择工具的参数。

top_logprobsinteger

介于 0 和 8 之间的整数，指定每个 token 位置返回多少个最可能的 token。

truncationstring

模型响应使用的截断策略。

代码示例

**响应示例：**

curl -s https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4.7",
    "input": "What is the meaning of life?"
  }'

import { xai } from "@ai-sdk/xai";
import { generateText } from "ai";

const result = await generateText({
  model: xai.responses("grok-4.7"),
  prompt: "What is the meaning of life?",
});

console.log(JSON.stringify(result, null, 2));

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.7",
    input="What is the meaning of life?",
)

print(response.model_dump_json(indent=2))

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const response = await client.responses.create({
  model: "grok-4.7",
  input: "What is the meaning of life?",
});

console.log(JSON.stringify(response, null, 2));

{
  "input": [
    {
      "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"
}

{
  "created_at": 1774274151,
  "completed_at": 1774274155,
  "id": "e7fd6e3f-0a77-9948-99a9-b40ba7c1c6f1",
  "max_output_tokens": null,
  "model": "grok-4.20-0309-reasoning",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "type": "output_text",
          "text": "**42.**",
          "logprobs": [],
          "annotations": []
        }
      ],
      "id": "msg_e7fd6e3f-0a77-9948-99a9-b40ba7c1c6f1",
      "role": "assistant",
      "type": "message",
      "status": "completed"
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "temperature": 0.7,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 0.95,
  "usage": {
    "input_tokens": 131,
    "input_tokens_details": {
      "cached_tokens": 128
    },
    "output_tokens": 624,
    "output_tokens_details": {
      "reasoning_tokens": 246
    },
    "total_tokens": 755,
    "num_sources_used": 0,
    "num_server_side_tools_used": 0,
    "cost_in_usd_ticks": 37756000
  },
  "user": null,
  "incomplete_details": null,
  "status": "completed",
  "store": true,
  "metadata": {},
  "background": false,
  "service_tier": "default",
  "truncation": "disabled",
  "top_logprobs": 0,
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "prompt_cache_key": null,
  "max_tool_calls": null,
  "safety_identifier": null,
  "error": null,
  "instructions": null
}

获取之前的 response

/v1/responses/{response_id}

检索先前生成的响应。

路径参数

response_idstring

先前创建响应请求返回的响应 ID。

响应体

backgroundboolean

OpenResponses 兼容字段。目前未使用，仅用于 OpenResponses 兼容性。是否在后台异步处理响应。

created_atinteger

响应创建时间的 Unix 时间戳（秒）。

errorobject

模型未能生成响应时返回的错误对象。

frequency_penaltynumber

（Responses API 不支持）正值根据 token 在已有文本中的出现频率惩罚新 token，降低模型逐字重复同一行的可能性。

idstring

响应的唯一 ID。

metadataobject

仅为兼容性而包含。

modelstring

用于生成响应的模型名称。

objectstring

此资源的对象类型，始终为 `response`。

模型生成的响应。

parallel_tool_callsboolean

是否允许模型并行调用工具。

presence_penaltynumber

（Responses API 不支持）正值根据 token 是否已在文本中出现来惩罚新 token，提高模型讨论新话题的可能性。

service_tier"default" | "priority" | "fast"

（"default" | "priority" | "fast"，必填）

statusstring

响应状态，为 `completed`、`in_progress` 或 `incomplete`。

storeboolean

是否保存输入消息和模型响应，供稍后检索。

textobject

tool_choicestring | object

控制模型如何选择工具的参数。

top_logprobsinteger

介于 0 和 8 之间的整数，指定每个 token 位置返回多少个最可能的 token。

truncationstring

模型响应使用的截断策略。

No parameters.

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

删除之前的 response

/v1/responses/{response_id}

删除先前生成的响应。

路径参数

response_idstring

先前创建响应请求返回的响应 ID。

响应体

deletedboolean

是否成功删除响应。

idstring

要删除的 response_id。

objectstring

已删除对象的类型，始终为 `response`。

No parameters.

{
  "id": "ad5663da-63e6-86c6-e0be-ff15effa8357",
  "object": "response",
  "deleted": true
}

压缩对话

/v1/responses/compact

将完整的 Responses API 输入窗口压缩为更短的规范窗口。

请求体

传递给 `/v1/response` 请求的输入内容。

modelstring

用于压缩摘要的模型（必填）。

响应体

created_atinteger

压缩后对话的创建时间，以 Unix 时间戳（秒）表示。

idstring

本次压缩的唯一 ID（例如 `cmp_<uuid>`）。

modelstring

用于压缩摘要的模型。

objectstring

始终为 `"response.compaction"`。

outputarray<object | object | object | object | object>

压缩后的输出，包含一个压缩项。将其原样作为下一次 `/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.7",
    "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."}
    ]
  }'

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

compacted = client.responses.compact(
    model="grok-4.7",
    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."
            ),
        },
    ],
)

print(compacted.model_dump_json(indent=2))

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

const compacted = await client.responses.compact({
  model: "grok-4.7",
  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.",
    },
  ],
});

console.log(JSON.stringify(compacted, null, 2));

{
  "model": "latest",
  "input": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Tell me about Rust."
    },
    {
      "role": "assistant",
      "content": "Rust is a systems programming language..."
    },
    {
      "role": "user",
      "content": "How does ownership work?"
    },
    {
      "role": "assistant",
      "content": "Ownership in Rust is..."
    }
  ]
}

{}

最后更新：2026 年 9 月 14 日