Inference API
Batches
POST /v1/batches
创建一个新的批次来处理请求。
Request Body
name(string, required) — 创建的批次的名称。
Response Body
batch_id(string, required) — 批次的 ID。cancel_by_xai_message(string | null) — 如果批次被 xAI 取消，解释原因的错误信息。cancel_time(string | null) — 批次被取消的时间。create_api_key_id(string, required) — 用于创建批次的 API 密钥 ID。create_time(string, required) — 批次创建的时间。expire_time(string | null) — 批次过期的时间。name(string, required) — 批次的可读名称。state(object, required) — 包含有关批次进程当前状态的聚合信息。num_cancelled(integer, required) — 已取消的请求数量。num_error(integer, required) — 以错误结束的请求数量。num_pending(integer, required) — 待处理的请求数量。num_requests(integer, required) — 批次中的总请求数量。num_success(integer, required) — 成功完成的请求数量。
Request example:
{
"name": "My New Batch"
}Response example:
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "My New Batch",
"create_time": "2025-11-11",
"expire_time": "2025-11-12",
"create_api_key_id": "********-****-****-****-************",
"cancel_time": null,
"cancel_by_xai_message": null,
"state": {
"num_requests": 0,
"num_pending": 0,
"num_success": 0,
"num_error": 0,
"num_cancelled": 0
}
}GET /v1/batches
列出当前团队的所有批次。
Query Parameters
limit(integer | null) — 返回的元素数量。pagination_token(string | null) — 用于检索特定页面的可选页面令牌。由ListBatchesResponse中的pagination_token提供。
Response Body
batches(array<object>, required) — 批次的信息。batch_id(string, required) — 批次的 ID。cancel_by_xai_message(string | null) — 如果批次被 xAI 取消，解释原因的错误信息。cancel_time(string | null) — 批次被取消的时间。create_api_key_id(string, required) — 用于创建批次的 API 密钥 ID。create_time(string, required) — 批次创建的时间。expire_time(string | null) — 批次过期的时间。name(string, required) — 批次的可读名称。state(object, required) — 包含有关批次进程当前状态的聚合信息。num_cancelled(integer, required) — 已取消的请求数量。num_error(integer, required) — 以错误结束的请求数量。num_pending(integer, required) — 待处理的请求数量。num_requests(integer, required) — 批次中的总请求数量。num_success(integer, required) — 成功完成的请求数量。
pagination_token(string | null) — 用于检索下一批次页面的页面令牌。如果是最后一页，将为空。
Response example:
{
"batches": [
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "My New Batch",
"create_time": "2025-11-11",
"expire_time": "2025-11-12",
"create_api_key_id": "********-****-****-****-************",
"cancel_time": null,
"cancel_by_xai_message": null,
"state": {
"num_requests": 0,
"num_pending": 0,
"num_success": 0,
"num_error": 0,
"num_cancelled": 0
}
},
{
"batch_id": "batch_bac0e657-6bbf-46ba-a671-1d73a67c132a",
"name": "MyNewBatch",
"create_time": "2025-11-09",
"expire_time": "2025-11-10",
"create_api_key_id": "********-****-****-****-************",
"cancel_time": "2025-11-09",
"cancel_by_xai_message": null,
"state": {
"num_requests": 1,
"num_pending": 0,
"num_success": 1,
"num_error": 0,
"num_cancelled": 0
}
}
]
}GET /v1/batches/
获取特定批次的信息。
Path Parameters
batch_id(string, required) — 批次的唯一标识符
Response Body
batch_id(string, required) — 批次的 ID。cancel_by_xai_message(string | null) — 如果批次被 xAI 取消，解释原因的错误信息。cancel_time(string | null) — 批次被取消的时间。create_api_key_id(string, required) — 用于创建批次的 API 密钥 ID。create_time(string, required) — 批次创建的时间。expire_time(string | null) — 批次过期的时间。name(string, required) — 批次的可读名称。state(object, required) — 包含有关批次进程当前状态的聚合信息。num_cancelled(integer, required) — 已取消的请求数量。num_error(integer, required) — 以错误结束的请求数量。num_pending(integer, required) — 待处理的请求数量。num_requests(integer, required) — 批次中的总请求数量。num_success(integer, required) — 成功完成的请求数量。
Response example:
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "My New Batch",
"create_time": "2025-11-11",
"expire_time": "2025-11-12",
"create_api_key_id": "********-****-****-****-************",
"cancel_time": null,
"cancel_by_xai_message": null,
"state": {
"num_requests": 0,
"num_pending": 0,
"num_success": 0,
"num_error": 0,
"num_cancelled": 0
}
}GET /v1/batches/{batch_id}/requests
列出批次中所有请求的元数据。
Path Parameters
batch_id(string, required) — 批次的唯一标识符
Query Parameters
limit(integer | null) — 单页返回的最大项目数（最大 1000）pagination_token(string | null) — 用于检索下一页结果的令牌
Response Body
batch_request_metadata(array<object>, required) — 给定批次的批次请求元数据。batch_request_id(string, required) — 请求的 ID。在批次内唯一。create_time(string, required) — 记录请求的时间。endpoint(string, required) — 要查询的 API 端点。finish_time(string | null) — 记录响应的时间。model(string, required) — 要查询的模型名称。state("unknown" | "pending" | "succeeded" | "cancelled" | "failed", required)
pagination_token(string | null) — 用于从下一页检索结果的页面令牌。如果是最后一页，将为空。
Response example:
{
"batch_request_metadata": [
{
"batch_request_id": "test_request_0",
"endpoint": "xai_api.Chat/GetCompletion",
"model": "grok-4",
"state": "succeeded",
"create_time": "2025-11-11",
"finish_time": "2025-11-12"
}
],
"pagination_token": null
}POST /v1/batches/{batch_id}/requests
向现有批次添加多个请求。
Path Parameters
batch_id(string, required) — 批次的唯一标识符
Request Body
batch_requests(array<object>, required) — 要添加到批次中的批次请求列表batch_request(object, required)chat_get_completion(object, required) — 用于/v1/chat/completions端点的聊天请求体。deferred(boolean | null) — 如果设置为true，请求将返回一个request_id。然后可以通过 GET/v1/chat/deferred-completion/{request_id}获取延迟响应。frequency_penalty(number | null) — （推理模型不支持）介于 -2.0 和 2.0 之间的数字。正值会根据新 tokens 在文本中已有的频率来惩罚它们，降低模型逐字重复相同行的可能性。logit_bias(object | null) — （不支持）一个 JSON 对象，将 tokens（由其在 tokenizer 中的 token ID 指定）映射到 -100 到 100 之间的关联偏差值。从数学上讲，该偏差会添加到模型生成的 logits 之前进行采样。确切效果会因模型而异，但 -1 到 1 之间的值应该会降低或提高选择的概率；像 -100 或 100 这样的值应该会导致禁止或选择相关 token。logprobs(boolean | null) — 是否返回输出 tokens 的对数概率。如果为 true，返回消息内容中每个输出 token 的对数概率。max_completion_tokens(integer | null) — 生成的完成 token 数量的上限，仅适用于可见输出 tokens（即不适用于用于推理或函数调用的 tokens）。默认为 None，意味着模型将根据需要生成尽可能多的 tokens，直到达到模型的最大上下文长度。max_tokens(integer | null) — [已弃用] 聊天完成中可以生成的最大 token 数量。已弃用，改为使用max_completion_tokens。messages(array<object | object | object | object | object>) — 构成聊天对话的消息列表。不同的模型支持不同的消息类型，例如图像和文本。model(string) — 要使用的模型名称。可从 https://console.x.ai/team/default/models 或 https://docs.x.ai/docs/models 获取。n(integer | null) — 为每个输入消息生成多少个聊天完成选项。请注意，您将根据所有选项中生成的 tokens 数量计费。保持 n 为 1 以最小化成本。parallel_tool_calls(boolean | null) — 如果设置为 false，模型最多可以执行一个工具调用。presence_penalty(number | null) — （grok-3和推理模型不支持）介于 -2.0 和 2.0 之间的数字。正值会根据新 tokens 是否已出现在文本中来惩罚它们，增加模型谈论新主题的可能性。reasoning_effort(string | null) — 限制推理模型在响应前思考的难度。grok-4不支持，如果与grok-4一起使用将导致错误。可能值为low（使用更少的推理 tokens）和high（使用更多的推理 tokens）。response_format(object | object | object)search_parameters(object)from_date(string | null) — 考虑结果的起始日期，使用 ISO-8601 YYYY-MM-DD 格式。参见 https://en.wikipedia.org/wiki/ISO_8601。max_search_results(integer | null) — 使用的最大搜索结果数。mode(string | null) — 选择查询实时数据的模式：off：不执行搜索，不考虑外部数据。on（默认）：模型将在所有来源中搜索相关数据。auto：模型选择是否搜索数据以及在哪里搜索数据。
return_citations(boolean | null) — 是否在响应中返回引用。sources(array | null) — 要搜索的来源列表。如果未指定来源，模型默认将在网络和 X 上搜索。to_date(string | null) — 考虑结果的截止日期，使用 ISO-8601 YYYY-MM-DD 格式。参见 https://en.wikipedia.org/wiki/ISO_8601。
seed(integer | null) — 如果指定，我们的系统将尽力进行确定性采样，使得具有相同seed和参数的重复请求应返回相同的结果。不保证确定性，您应参考system_fingerprint响应参数来监控后端的更改。stop(array | null) — （推理模型不支持）最多 4 个序列，API 在这些序列处将停止生成更多 tokens。stream(boolean | null) — 如果设置，将发送部分消息增量。Tokens 将在可用时作为仅数据的 server-sent 事件发送，流以data: [DONE]消息终止。stream_options(object)include_usage(boolean, required) — 设置在data: [DONE]消息之前要流式传输的额外块。其他块将在usage字段中返回null。
temperature(number | null) — 要使用的采样温度，介于 0 和 2 之间。较高的值如 0.8 会使输出更随机，而较低的值如 0.2 会使输出更专注和确定性。tool_choice(string | object)tools(array | null) — 模型可能调用的工具列表，采用 JSON-schema 格式。目前，仅支持函数作为工具。使用此提供模型可能为其生成 JSON 输入的函数列表。最多支持 128 个函数。top_logprobs(integer | null) — 0 到 8 之间的整数，指定在每个 token 位置返回的最可能 tokens 的数量，每个 token 都有关联的对数概率。如果使用此参数，必须将 logprobs 设置为 true。top_p(number | null) — 使用temperature采样的替代方法，称为 nucleus 采样，其中模型考虑具有top_p概率质量的 tokens 的结果。因此 0.1 表示只考虑概率质量前 10% 的 tokens。通常建议修改此参数或temperature，但不要同时修改两者。user(string | null) — 代表最终用户的唯一标识符，可以帮助 xAI 监控和检测滥用行为。web_search_options(object)filters(object) — 仅包含用于兼容性。search_context_size(string | null) — 此字段包含用于与 OpenAI API 兼容。它映射到max_search。user_location(object) — 仅包含用于兼容性。
batch_request_id(string | null) — 为输入请求提供的用户标识符。如果提供，它必须在批次内唯一。 用于在响应返回给用户时标识相应的结果。 这是因为返回结果的顺序不一定与请求的顺序相同。
Request example:
{
"batch_requests": [
{
"batch_request_id": "test_request_0",
"batch_request": {
"chat_get_completion": {
"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": "grok-4"
}
}
}
]
}GET /v1/batches/{batch_id}/results
列出批次的处理结果。
Path Parameters
batch_id(string, required) — 批次的唯一标识符
Query Parameters
limit(integer | null) — 单页返回的最大项目数（最大 1000）pagination_token(string | null) — 用于检索下一页结果的令牌
Response Body
pagination_token(string | null) — 用于从下一页检索结果的页面令牌。如果是最后一页，将为空。results(array<object>, required) — 已处理的结果。batch_request_id(string, required) — 输入请求的用户提供或生成的标识符。如果用户在BatchRequest中提供了batch_request_id，该值将匹配用户提供的值。 该值在批次内唯一。batch_result(object | object, required)error(string, required)response("unknown" | object, required)chat_get_completion(object, required) — 用于/v1/chat/completions端点的聊天响应体。choices(array<object>, required) — 来自模型的响应选项列表。长度对应于请求体中的n（默认为 1）。finish_reason(string | null) — 完成原因。"stop"表示推理已达到模型定义的或用户在stop中提供的停止序列。"length"表示推理结果已达到模型允许的最大 token 长度或用户在max_tokens中定义的值。流式模式中的"end_turn"或null当块不是最后一个时。index(integer, required) — 响应选项中选项的索引，从 0 开始。logprobs(object)content(array | null) — 返回的每个输出 token 的对数概率数组。
message(object, required)content(string | null) — 消息的内容。reasoning_content(string | null) — 模型生成的推理跟踪。refusal(string | null) — 模型无法生成响应时给出的原因。如果模型能够生成，则为 null。role(string, required) — 消息所属的角色，模型的响应始终是"assistant"。tool_calls(array | null) — 模型要求用户执行的工具调用列表。
citations(array | null) — 模型用于回答的所有外部页面列表。created(integer, required) — 聊天完成创建时间，Unix 时间戳。debug_output(object)attempts(integer, required) — 对模型的尝试次数。cache_read_count(integer, required) — 缓存读取次数cache_read_input_bytes(integer, required) — 缓存读取大小cache_write_count(integer, required) — 缓存写入次数cache_write_input_bytes(integer, required) — 缓存写入大小chunks(array<string>, required) — 从采样器管道返回的各个块。engine_request(string, required) — 发送到推理引擎的 JSON 序列化请求。lb_address(string, required) — 负载均衡器地址prompt(string, required) — 发送到模型的文本形式的提示。request(string, required) — 从用户收到的请求。responses(array<string>, required) — 从模型收到的响应。sampler_checkpoint_mount(string, required) — 为服务此请求的采样器提供的基础检查点挂载路径。sampler_tag(string, required) — 位于 GTP 地址后面的实际引擎的标签。例如 "grok-4-code-eapi-lap4-unified-sblbm-0"
id(string, required) — 聊天响应的唯一 ID。model(string, required) — 用于创建聊天完成的模型 ID。object(string, required) — 对象类型，始终为"chat.completion"。system_fingerprint(string | null) — 系统指纹，用于指示 xAI 系统配置更改。usage(object)completion_tokens(integer, required) — 使用的完成 token 总数。completion_tokens_details(object, required) — 完成使用详情。accepted_prediction_tokens(integer, required) — 出现在完成中的预测中的 token 数量。audio_tokens(integer, required) — 模型生成的音频输入 tokens。reasoning_tokens(integer, required) — 模型为推理生成的 tokens。rejected_prediction_tokens(integer, required) — 未出现在完成中的预测中的 token 数量。
num_sources_used(integer, required) — 使用的单个实时搜索源数量。`
num_success(integer, required) — 已成功完成的请求数量。
响应示例：
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "My New Batch",
"create_time": "2025-11-11",
"expire_time": "2025-11-12",
"create_api_key_id": "********-****-****-****-************",
"cancel_time": "2025-11-11",
"cancel_by_xai_message": null,
"state": {
"num_requests": 1,
"num_pending": 0,
"num_success": 1,
"num_error": 0,
"num_cancelled": 0
}
}