本文覆盖 Grok 系列在 /v1/chat/completions 端点上的全部对话类能力，所有结论基于 2026年7月13日 (UTC+8) 在 API易 网关的实测。
基础对话与流式输出 全系 6 个模型均支持标准 OpenAI 格式与流式输出，stream_options: {"include_usage": true} 实测可用（末尾 chunk 返回完整 usage）：
from openai import OpenAI client = OpenAI( api_key = "sk-your-api-key" , base_url = "https://api.apiyi.com/v1" ) stream = client.chat.completions.create( model = "grok-4.3" , messages = [{ "role" : "user" , "content" : "从1数到5，每个数字一行" }], stream = True , stream_options = { "include_usage" : True }, ) for chunk in stream: if chunk.choices and chunk.choices[ 0 ].delta.content: print (chunk.choices[ 0 ].delta.content, end = "" ) if chunk.usage: print ( f " \n 用量: { chunk.usage.total_tokens } tokens" )
实测流式首 token 延迟 1.5–2.3 秒（全模型），非流式短问答整体延迟 1.7–5.1 秒。
思维链（Reasoning） 这是 Grok 系列最容易被误解的计费点，务必读完本节。
哪些模型输出思维链 模型 思维链行为 grok-4.5 / grok-4.3 / grok-build-0.1默认开启 ，响应含 reasoning_content 字段，无法关闭grok-4.20-0309-reasoning开启，含 reasoning_content grok-4.20-0309-non-reasoning关闭，reasoning_tokens 为 0，直接快答 grok-4.20-multi-agent-beta-0309内部推理不外露，但 reasoning_tokens 照常计费
推理 tokens 计入输出计费 。实测一条短问答：可见回答仅 30 tokens，实际计费输出 586 tokens（其中推理 556 tokens）。高频短问答场景选 grok-4.20-0309-non-reasoning 可显著省成本。
读取思维链与推理用量 resp = client.chat.completions.create( model = "grok-4.20-0309-reasoning" , messages = [{ "role" : "user" , "content" : "A管8小时注满水池，B管12小时，同开需几小时？" }] ) msg = resp.choices[ 0 ].message print ( "回答:" , msg.content) print ( "思维链:" , msg.reasoning_content) # 推理过程文本 print ( "推理 tokens:" , resp.usage.completion_tokens_details.reasoning_tokens)
reasoning_effort 参数 reasoning_effort（如 "low" / "high"）仅 grok-4.5 接受 ；grok-4.20-0309-reasoning 会明确报错 Model ... does not support parameter reasoningEffort（400）。跨模型代码请勿硬编码该参数。结构化输出（Structured Outputs） 支持 OpenAI 标准的 response_format: json_schema（strict 模式），实测 grok-4.5 / grok-4.3 / grok-build-0.1 / grok-4.20-0309-reasoning / multi-agent 模型全部通过，返回严格符合 schema 的 JSON：
resp = client.chat.completions.create( model = "grok-4.5" , messages = [{ "role" : "user" , "content" : "张三今年25岁，住在杭州。请抽取信息。" }], response_format = { "type" : "json_schema" , "json_schema" : { "name" : "user_info" , "strict" : True , "schema" : { "type" : "object" , "properties" : { "name" : { "type" : "string" }, "age" : { "type" : "integer" }, "city" : { "type" : "string" } }, "required" : [ "name" , "age" , "city" ], "additionalProperties" : False } } } ) print (resp.choices[ 0 ].message.content) # {"name":"张三","age":25,"city":"杭州"}
函数调用（Function Calling） 支持 OpenAI 标准的 tools / tool_choice 字段与完整的两轮工具调用流程（实测 grok-4.5 / grok-4.3 / grok-build-0.1 通过）：
tools = [{ "type" : "function" , "function" : { "name" : "get_weather" , "description" : "查询指定城市当前天气" , "parameters" : { "type" : "object" , "properties" : { "city" : { "type" : "string" , "description" : "城市名" }}, "required" : [ "city" ] } } }] messages = [{ "role" : "user" , "content" : "上海现在天气怎么样？" }] # 第一轮：模型决定调用工具 resp = client.chat.completions.create( model = "grok-4.5" , messages = messages, tools = tools) msg = resp.choices[ 0 ].message tool_call = msg.tool_calls[ 0 ] print (tool_call.function.name, tool_call.function.arguments) # get_weather {"city":"上海"} # 第二轮：喂回工具执行结果 messages += [ msg, { "role" : "tool" , "tool_call_id" : tool_call.id, "content" : '{"city": "上海", "temp_c": 31, "condition": "晴"}' } ] resp2 = client.chat.completions.create( model = "grok-4.5" , messages = messages, tools = tools) print (resp2.choices[ 0 ].message.content) # 上海现在天气晴朗，气温31℃。
tool_choice 强制调用（{"type": "function", "function": {"name": "get_weather"}}）实测同样可用。这里说的是客户端函数调用 （工具由你的代码执行）。如果想让 xAI 服务端替你执行搜索 / 跑代码 / 连 MCP，请走 Responses API，见 联网搜索与 X 搜索 和 代码执行与 MCP 。 视觉输入（图片理解） Grok 4.x 对话模型支持图片输入（jpg / png，单图不大于 20MiB），使用 OpenAI Vision 兼容格式。实测 grok-4.5 / grok-4.3 / grok-4.20-0309-non-reasoning 均正确识别图形与颜色：
import base64 with open ( "image.jpg" , "rb" ) as f: b64 = base64.b64encode(f.read()).decode() resp = client.chat.completions.create( model = "grok-4.5" , messages = [{ "role" : "user" , "content" : [ { "type" : "text" , "text" : "图里有什么？" }, { "type" : "image_url" , "image_url" : { "url" : f "data:image/jpeg;base64, { b64 } " }} ] }] ) print (resp.choices[ 0 ].message.content)
优先使用 base64 data URL 。传外链 URL 时，图片由 xAI 上游服务器直接抓取——实测部分图床（如维基媒体）会对服务器抓取返回错误，导致请求失败（image_download_error）。若必须用外链，请确保图床对服务端请求开放且 URL 直接指向图片文件。
Prompt Caching（自动缓存） Grok 前缀缓存自动生效，无需任何配置 。同前缀请求实测第二次起命中 2688/2735 tokens，命中部分按缓存折扣价计费：
resp = client.chat.completions.create( model = "grok-4.5" , messages = messages) print ( "缓存命中:" , resp.usage.prompt_tokens_details.cached_tokens)
优化建议：把稳定不变的 system prompt / few-shot 示例放在消息最前面，可变内容放最后，最大化前缀命中。API易 网关为号池模式，缓存命中率请做合理预期（不承诺 100% 命中），计费口径详见 缓存计费说明 。
常见问题
关不掉。grok-4.5 / grok-4.3 / grok-build-0.1 的内部推理是模型固有行为。若不需要思维链、追求快答低成本，直接改用 grok-4.20-0309-non-reasoning。
reasoning_content 会计入下一轮上下文吗？
多轮对话回传历史时，只需回传 content（和工具调用相关字段），不要把 reasoning_content 塞回 messages——它不是标准字段，回传徒增输入 tokens。
推理模型的思维链也消耗输出配额，max_tokens 给小了会导致思维链吃满配额、正文被截断。带推理的模型建议 max_tokens 至少 2048 起步。
可以正常传入。注意推理类模型对采样参数的敏感度低于传统模型，调优价值有限。
相关文档
联网搜索与 X 搜索 server-side 联网工具实战
