HiAPI
Zh
博客

教程

如何使用 grok-4.6 API：cURL、Python 与一个可用的请求

在 hiapi 兼容 OpenAI 的聊天补全端点上使用流式输出、工具调用与 JSON 模式

2026年11月3日
如何使用 grok-4.6 API：cURL、Python 与一个可用的请求

grok-4.6 是一个经过推理调优的聊天模型，可通过 hiapi API 使用。与 hiapi 的图像和视频模型不同，它不使用异步的 /v1/tasks 管道——它是一个同步的、兼容 OpenAI 的聊天补全接口，因此你会直接得到一个普通的 HTTP 响应（或一条 SSE 流），无需轮询。本文先介绍一个最小可用的请求，然后讲解你在生产环境中真正需要的部分：流式输出、工具调用、JSON 模式以及错误处理。

你需要准备什么

  • 一个 hiapi API 密钥。如果你还没有，请从控制台获取一个——下面每个请求都需要将它放在 Authorization: Bearer sk-... 请求头中。
  • 任意 HTTP 客户端。示例使用 curl 和 Python 的 requests；无论使用哪种语言，JSON 结构都是一样的。
  • 不需要 SDK。grok-4.6 的请求/响应格式非常贴近 OpenAI 聊天补全的约定，因此兼容 OpenAI 的工具通常都能用，但 hiapi 提供的是自己的聊天补全端点，而不是专有端点——把客户端指向 https://api.hiapi.ai/v1/chat/completions，并使用裸模型 ID grok-4.6。

最小可用请求

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "user", "content": "用一句话解释卡尔曼滤波器的作用。"}
    ]
  }'

成功响应如下所示：

{
  "id": "b6c018d3-218e-9b06-aa12-5afc02e21b5c",
  "object": "chat.completion",
  "model": "grok-4.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "卡尔曼滤波器通过将带噪声的测量值与预测模型相结合，并按各自的不确定性加权，来估计系统随时间变化的真实状态。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 31,
    "total_tokens": 55
  }
}

答案文本位于 choices[0].message.content，与任何 OpenAI 风格的聊天 API 一样。

下面是使用 requests 的同一调用在 Python 中的写法：

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [
            {"role": "user", "content": "用一句话解释卡尔曼滤波器的作用。"}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

grok-4.6 的推理调节项

grok-4.6 是一个推理模型：在写出最终答案之前，它会花费额外 token 进行“思考”，这些推理 token 会按输出 token 计费（当前费率见定价）。你可以通过 reasoning_effort 控制思考量，取值为 low、medium、high 或 xhigh 之一（如果省略，API 默认为 high）：

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "用五个词打个招呼。"}],
    "reasoning_effort": "low"
  }'

非流式响应会在 message.reasoning_content 中提供模型的推理轨迹，与最终的 message.content 分开。对于简短、低延迟的任务，可降至 low 或 medium；对于多步问题，high 或 xhigh 会以延迟和 token 换取更好的答案。

流式响应

设置 "stream": true，以 Server-Sent Events 形式读取响应，而不是等待完整补全：

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "从 1 数到 5。"}],
    "stream": true
  }'

每一行都是一个 data: {...} 数据块。推理 token 通过 choices[0].delta.reasoning_content 流式传输，然后答案 token 通过 choices[0].delta.content 流式传输，流以字面量 data: [DONE] 结束：

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"reasoning_content":"列出"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1, 2"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

在 Python 中，requests 可以逐行迭代流：

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [{"role": "user", "content": "从 1 数到 5。"}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        payload = line[len(b"data: "):]
        if payload == b"[DONE]":
            break
        chunk = json.loads(payload)
        delta = chunk["choices"][0]["delta"]
        if "content" in delta:
            print(delta["content"], end="", flush=True)

工具调用

grok-4.6 支持 OpenAI 风格的函数调用：传入 tools 数组，并通过 tool_choice: "auto" 让模型自行决定何时调用某个工具。

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "东京的天气怎么样？"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "获取某个城市的当前天气",
          "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

当模型决定调用该工具时，finish_reason 会返回 "tool_calls"，参数会以 JSON 字符串形式到达，需要你自己解析：

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_...",
            "type": "function",
            "function": {"name": "get_weather", "arguments": "{\"city\":\"Tokyo\"}"}
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

运行你的函数，然后将一条 role: "tool" 的消息（包含运行结果和匹配的 tool_call_id）追加到 messages，再把对话发回，以获得最终的自然语言回答。

JSON 模式

如果你希望无需工具调用往返就能解析响应，可以设置 response_format：

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "system", "content": "请用一个包含 \"city\" 和 \"country\" 两个键的 JSON 对象来回答。"},
      {"role": "user", "content": "埃菲尔铁塔在哪里？"}
    ],
    "response_format": {"type": "json_object"}
  }'

message.content 会以 JSON 字符串形式返回（仍然位于普通的聊天补全信封中），你在自己这边用 json.loads(...) 解析即可。请务必在提示词中指示模型实际生成 JSON——response_format 会约束输出格式，但不会替你构造 schema。

生产环境实践

  • 处理已记录的錯誤码。 密钥错误或缺失会返回 HTTP 401，响应体为 {"error":{"code":"permission_denied","message":"...","request_id":"...","type":"hiapi_error"}}。余额不足返回 402；模型 ID 无效或参数格式错误返回 400。先检查状态码，并记录错误响应体中的 request_id——如果你需要报告问题，这正是你会用到的信息。
  • 对 429 和 503 采用退避重试。 hiapi 会按账户执行速率限制；429 表示你已超限，503 表示模型暂时不可用。两者都适合使用有上限的指数退避重试（例如 1 秒、2 秒、4 秒，尝试若干次后放弃），而不是紧密循环。
  • 设置请求超时。 在 high 或 xhigh 推理强度下，耗时明显长于 low；请根据所用强度级别设置客户端超时，而不是使用单一的全局常量。
  • 任何面向用户的场景都优先使用流式输出。 非流式调用会阻塞，直到完整响应（包括所有推理 token）就绪；流式输出可以立即将首批 token 送到你的 UI，并让你在 reasoning_content 增量先于最终答案到达时展示“思考中”状态。
  • 不要硬编码密钥。 从环境变量或密钥管理器加载，切勿从源代码管理中读取——上面的示例正是出于这个原因从 $HIAPI_API_KEY / os.environ["HIAPI_API_KEY"] 读取。

完整的参数参考（包括 grok-4.6 接受的每个字段）请参见模型页面和 grok-4.6 文档。

常见问题

hiapi 上的 grok-4.6 兼容 OpenAI SDK 吗？ 请求和响应结构遵循 OpenAI 聊天补全的约定（messages、choices[0].message.content、流式增量、工具调用），因此大多数允许覆盖基础 URL 和模型 ID 的兼容 OpenAI 的工具应该都能用。将基础 URL 指向 https://api.hiapi.ai/v1，并使用 grok-4.6 作为模型 ID。

为什么我的响应比其他模型慢？ grok-4.6 在回答前会花费 token 进行一次内部推理，这些 token 按输出 token 计费。对于延迟敏感的调用，将 reasoning_effort 降至 low 或 medium，或改用流式输出，这样就不必一次性等待整个响应。

reasoning_content 是什么意思，我可以对用户隐藏它吗？ 它是模型的中间推理轨迹，与 content 分开返回（流式传输时则以 delta.reasoning_content 形式返回）。你完全可以在 UI 中不渲染它——只有 content 才是最终答案。

我收到了 401 和 permission_denied——哪里出了问题？ 你的 Authorization 请求头缺失、格式错误，或者密钥无效/已被撤销。请重新检查你是否发送了 Authorization: Bearer sk-...，并且使用的是控制台中有效的密钥。

我可以在同一个请求中同时使用 grok-4.6 的函数调用和 JSON 模式吗？ tools/tool_choice 与 response_format 是相互独立的参数，可以同时设置，但如果模型决定调用工具，该轮的 finish_reason 会是 "tool_calls"，且 message.content 可能为空——请先处理工具调用，然后在后续轮次中请求最终的 JSON 格式答案。

如何控制成本？ 推理 token 计入输出 token，因此成本会随 reasoning_effort 和响应长度而变化。在运行高负载任务之前，请查看定价页面上的当前每 token 费率。

标签grokchat-completionsTutorial

相关文章

查看全部文章 →

立即开始构建持久 AI 产物

获取 API 密钥，通过一个基于任务（task）的 API 调用图像、视频和音频模型。

阅读 API 文档