推理 API
传统版与已弃用
POST /v1/completions
(传统版 - 推理模型不支持) 为给定提示创建文本补全响应。已被 /v1/chat/completions 替代。
请求体
best_of(integer | null) — (不支持) 在内部生成多个补全并返回得分最高的一个。目前尚未实现。echo(boolean | null) — 选项，用于在响应中包含原始提示以及生成的补全内容。frequency_penalty(number | null) — (不支持) -2.0 到 2.0 之间的数字。正值会根据新令牌在文本中已有的频率对其进行惩罚，降低模型逐字重复相同行的可能性。logit_bias(object | null) — (不支持) 接受一个将令牌映射到 -100 到 100 之间关联偏差值的 JSON 对象。您可以使用此分词器工具将文本转换为令牌 ID。从数学上讲，偏差值会添加到模型生成的 logits 中，然后再进行采样。确切效果会因模型而异，但 -1 到 1 之间的值应该会降低或提高选择的可能性；像 -100 或 100 这样的值应该会导致禁止或专门选择相关令牌。logprobs(boolean | null) — 在logprobs个最可能的输出令牌上包含对数概率，以及所选令牌。例如，如果logprobs为 5，API 将返回 5 个最可能令牌的列表。API 将始终返回采样令牌的对数概率，因此响应中可能有最多logprobs+1个元素。不支持grok-4.20及更新版本的模型；如果设置此字段，它将被静默忽略。max_tokens(integer | null) — 限制输出中可以生成的令牌数量。确保提示令牌和max_tokens的总和不超过模型的上下文限制。model(string) — 指定用于请求的模型。n(integer | null) — 确定每个提示要生成多少个补全序列。请谨慎使用，因为它会消耗大量令牌；相应地调整max_tokens和停止序列。presence_penalty(number | null) — (不被grok-3和推理模型支持) -2.0 到 2.0 之间的数字。正值会根据新令牌是否已在文本中出现对其进行惩罚，增加模型谈论新主题的可能性。prompt(string | array<string>)seed(integer | null) — 如果指定，我们的系统将尽力进行确定性采样，使得具有相同种子和参数的重复请求应返回相同结果。不保证确定性，您应该参考system_fingerprint响应参数来监控后端的变化。stop(array | null) — (推理模型不支持) 最多 4 个序列，API 将在这些位置停止生成更多令牌。stream(boolean | null) — 是否流式返回部分进度。如果设置，令牌将在可用时作为仅数据的 server-sent events 发送，流式传输以data: [DONE]消息终止。stream_options(object)include_usage(boolean, required) — 设置在data: [DONE]消息之前流式传输的额外块。其他块将在usage字段中返回null。
suffix(string | null) — (不支持) 生成文本后可选附加的字符串。temperature(number | null) — 使用的采样温度，介于 0 和 2 之间。较高的值如 0.8 会使输出更随机，而较低的值如 0.2 会使输出更专注和确定性。我们通常建议修改此值或top_p，但不要同时修改两者。top_p(number | null) — 温度采样的替代方法，称为核采样，其中模型考虑具有top_p概率质量的令牌结果。因此 0.1 意味着只考虑构成前 10% 概率质量的令牌。我们通常建议修改此值或温度，但不要同时修改两者。user(string | null) — 代表最终用户的唯一标识符，可以帮助 xAI 监控和检测滥用行为。
响应体
choices(array<object>, required) — 模型的响应选择列表。长度对应于请求体中的n（默认为 1）。finish_reason(string, required) — 完成原因。"stop"表示推理已达到模型定义的或在stop中用户提供的停止序列。"length"表示推理结果已达到模型的最大允许令牌长度或用户在max_tokens中定义的值。在流式模式中，当块不是最后一个时，为"end_turn"或null。index(integer, required) — 选择的索引。text(string, required) — 文本响应。
created(integer, required) — 聊天补全创建的 Unix 时间戳。id(string, required) — 请求的 ID。model(string, required) — 使用的模型。object(string, required) — 响应的对象类型。这始终是"text_completion"。system_fingerprint(string | null) — 系统指纹，用于指示 xAI 系统配置更改。usage(object)completion_tokens(integer, required) — 使用的总补全令牌数。completion_tokens_details(object, required) — 补全使用详情。accepted_prediction_tokens(integer, required) — 出现在补全中的预测令牌数量。audio_tokens(integer, required) — 模型生成的音频输入令牌。reasoning_tokens(integer, required) — 模型为推理生成的令牌。rejected_prediction_tokens(integer, required) — 未出现在补全中的预测令牌数量。
cost_in_usd_ticks(integer, required) — 此请求的精确成本，以 USD tick 为单位，其中 "tick" 定义如下： TICKS_IN_USD_CENT: i64 = 100_000_000 这意味着一美元中有 10'000'000'000 个 tick。num_sources_used(integer, required) — 使用的单个实时搜索源的数量。prompt_tokens(integer, required) — 使用的总提示令牌数。prompt_tokens_details(object, required) — 提示使用详情。audio_tokens(integer, required) — 使用的音频提示令牌。cached_tokens(integer, required) — xAI 从先前请求缓存并在此请求中重用的令牌。image_tokens(integer, required) — 使用的图像提示令牌。text_tokens(integer, required) — 使用的总文本提示令牌数（缓存 + 非缓存文本令牌）。
total_tokens(integer, required) — 使用的总令牌数，是提示令牌和补全令牌数量的总和。
请求示例：
{
"prompt": "1, 2, 3, 4, ",
"model": "grok-3",
"max_tokens": 3
}响应示例：
{
"id": "873492b3-6144-4279-ac2e-2c45242c5ce6",
"object": "text_completion",
"created": 1743771779,
"model": "grok-3",
"choices": [
{
"index": 0,
"text": "5, ",
"finish_reason": "length"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 3,
"total_tokens": 15,
"prompt_tokens_details": {
"text_tokens": 12,
"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"
}WARNING
已弃用：Anthropic SDK 兼容性已完全弃用。请迁移到 Responses API 或 gRPC。
POST /v1/messages
创建消息响应。此端点与 Anthropic API 兼容。
请求体
max_tokens(integer) — 停止前生成的最大令牌数。当模型达到停止序列时，它可能会在达到max_tokens之前停止。messages(array<object>) — 输入消息。content(string | array<object | object | object | object | object | object>, required)role(string, required) — 消息所属的角色，"system"表示系统提示，"user"表示用户提示，"assistant"表示模型的响应。
metadata(object)user_id(string | null) — 代表最终用户的唯一标识符，可以帮助 xAI 监控和检测滥用行为。
model(string) — 要使用的模型名称。stop_sequences(array | null) — (推理模型不支持) 最多 4 个序列，API 将在这些位置停止生成更多令牌。stream(boolean | null) — 如果设置，将发送部分消息增量。令牌将在可用时作为仅数据的 server-sent events 发送，流式传输以data: [DONE]消息终止。system(string | array<object>)temperature(number | null) — 使用的采样温度，介于 0 和 2 之间。较高的值如 0.8 会使输出更随机，而较低的值如 0.2 会使输出更专注和确定性。在推理模型上可能效果不佳。tool_choice(object | object | object)tools(array | null) — 模型可以调用的工具列表，以 JSON-schema 格式。目前，仅支持函数作为工具。使用此选项提供模型可以为其生成 JSON 输入的函数列表。最多支持 128 个函数。top_k(integer | null) — (不支持) 生成下一个令牌时，从 k 个最可能的选项中随机选择下一个令牌。top_p(number | null) — 使用temperature采样的替代方法，称为核采样，其中模型考虑具有top_p概率质量的令牌结果。因此 0.1 意味着只考虑构成前 10% 概率质量的令牌。通常建议修改此值或temperature，但不要同时修改两者。
响应体
content(array<object | object | object | object>, required) — 响应消息内容。id(string, required) — 唯一对象标识符。model(string, required) — 处理请求的模型名称。role(string, required) — 生成消息的角色。始终为"assistant"stop_reason(string | null) — 停止原因。"stop_sequence"表示推理已达到模型定义的或在stop中用户提供的停止序列。"max_tokens"表示推理结果已达到模型的最大允许令牌长度或用户在max_tokens中定义的值。在流式模式中，当块不是最后一个时，为"end_turn"或null。"tool_use"表示模型已调用工具并等待工具响应。stop_sequence(string | null) — 用于停止生成的自定义停止序列。type(string, required) — 对象类型。对于消息类型，这始终是"message"。usage(object, required)cache_creation_input_tokens(integer, required) — (不支持) 创建新条目时写入缓存的令牌数。cache_read_input_tokens(integer, required) — 为此请求从缓存中检索的令牌数。input_tokens(integer, required) — 使用的输入令牌数output_tokens(integer, required) — 使用的输出令牌数
请求示例：
{
"model": "latest",
"max_tokens": 32,
"messages": [
{
"role": "user",
"content": "Hello, world"
}
]
}响应示例：
{
"id": "4f224bfb-9d53-4c82-b40a-b7cd80831ec2",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello there! \"Hello, world\" is a classic, isn't it? Whether you're just saying hi or channeling your inner coder, I'm happy to greet you back"
}
],
"model": "latest",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 9,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"output_tokens": 32
}
}WARNING
已弃用：Anthropic SDK 兼容性已完全弃用。请迁移到 Responses API 或 gRPC。
POST /v1/complete
(传统版 - 推理模型不支持) 创建文本补全响应。此端点与 Anthropic API 兼容。
请求体
max_tokens_to_sample(integer) — 停止前生成的最大令牌数。metadata(object)user_id(string | null) — 代表最终用户的唯一标识符，可以帮助 xAI 监控和检测滥用行为。
model(string) — 用于补全的模型。prompt(string) — 模型执行补全的提示。stop_sequences(array | null) — (推理模型不支持) 最多 4 个序列，API 将在这些位置停止生成更多令牌。stream(boolean | null) — (不支持) 如果设置，将发送部分消息增量。令牌将在可用时作为仅数据的 server-sent events 发送，流式传输以data: [DONE]消息终止。temperature(number | null) — 使用的采样温度，介于 0 和 2 之间。较高的值如 0.8 会使输出更随机，而较低的值如 0.2 会使输出更专注和确定性。top_k(integer | null) — (不支持) 生成下一个令牌时，从 k 个最可能的选项中随机选择下一个令牌。top_p(number | null) — 使用temperature采样的替代方法，称为核采样，其中模型考虑具有top_p概率质量的令牌结果。因此 0.1 意味着只考虑构成前 10% 概率质量的令牌。通常建议修改此值或temperature，但不要同时修改两者。
响应体
completion(string, required) — 补全内容，包括但不限于停止序列。id(string, required) — 补全响应的 ID。model(string, required) — 处理请求的模型。stop_reason(string | null) — 停止补全的原因。"stop_sequence"表示推理已达到模型定义的或在stop中用户提供的停止序列。"length"表示推理结果已达到模型的最大允许令牌长度或用户在max_tokens中定义的值。在流式模式中，当块不是最后一个时，为"end_turn"或null。type(string, required) — 补全响应对象类型。这始终是"completion"。
请求示例：
{
"model": "grok-3",
"max_tokens_to_sample": 8,
"temperature": 0.1,
"prompt": "\n\nHuman: Hello, how are you?\n\nAssistant:"
}响应示例：
{
"type": "completion",
"id": "982044c5-760c-4c8d-8936-f906b5cedc26",
"completion": " Hey there! I'm doing great, thanks",
"stop_reason": "max_tokens",
"model": "grok-3"
}