博客

教程

如何通过 HiAPI API 使用 gpt-6-sol:curl、Python 与一次可用的请求

2026年11月12日
建筑风格的封面视觉:暖灰色混凝土平面被石板蓝色的斜向阴影切割,并带有一条细长的鼠尾草绿色接缝。
本页内容

首次调用之前需要准备什么

在写任何代码之前,先准备好三样东西。本教程的其余内容都以此为基础。

一个 HiAPI API 密钥

每次向 HiAPI API 发送请求都需要用 API 密钥进行身份验证。请在你的 HiAPI 账户仪表盘中创建一个密钥,并将其保存在安全的地方,最好放在环境变量中,而不是源代码文件里。要像对待密码一样对待它:一旦泄露,就立即轮换。

export HIAPI_API_KEY="your-api-key-here"

基础端点

本指南中的所有调用都发往 HiAPI API 的基础端点,每个模型都通过相同的请求路径形式来访问。你不需要为每个模型单独准备主机或 SDK——gpt-6-sol 是在请求体中选择的,而不是通过更改客户端设置来选择的。

一个 HTTP 客户端

你需要以下之一:

  • curl,在大多数 Linux 和 macOS 系统以及 Windows 终端中默认可用。
  • 安装了 requests 库的 Python(pip install requests),或者如果你不想引入依赖,也可以使用标准库 urllib。

不需要其他工具。你不需要特定供应商的 SDK,也不需要安装任何与模型相关的东西。只要你能发送一个带有 JSON 请求体和请求头的 HTTPS POST 请求,就能调用 gpt-6-sol。

现在值得养成的一个习惯:保留一个草稿文件,记录你正在使用的可用请求,这样当出现失败时,你可以将失败的调用与最近一次已知可用的调用进行对比。

使用 bearer 密钥进行身份验证

身份验证是首次调用中最容易出错的地方,因此值得认真对待。

Authorization 请求头

HiAPI API 期望你的密钥放在标准的 bearer 请求头中:

Authorization: Bearer $HIAPI_API_KEY

就是字面单词 Bearer、一个空格,然后是密钥。常见错误包括:遗漏 Bearer 这个词、复制值时带入多余的换行符,或者在客户端已经添加引号的情况下又给密钥加上引号。

内容类型必须是 JSON

请求携带 JSON 请求体,因此内容类型请求头必须匹配:

Content-Type: application/json

如果缺少此请求头,某些服务器仍会解析请求体,但你不应依赖这一点——要显式设置它。内容类型不匹配是导致请求验证错误的常见原因,这类错误看起来像是请求体错误。

最小请求头集合

你只需要上面两个请求头:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

保持请求头集合尽可能小。从其他 API 示例中借来的推测性请求头更可能造成困惑,而不是帮助。一旦使用这两个请求头的调用成功,你就有了一个干净的基线,可供以后对比。

避免将密钥直接粘贴到 shell 历史记录或已提交的文件中。像上面那样引用环境变量,可以让密钥远离你的源代码和终端历史记录。

为 gpt-6-sol 构建请求体

请求体是 JSON,其核心是一个消息列表。从最小配置开始;只有在调用成功后才添加字段。

最小请求负载

最小的有用请求体需要指定模型并提供一条消息:

{
  "model": "gpt-6-sol",
  "messages": [
    { "role": "user", "content": "用一句话解释什么是 API bearer token。" }
  ]
}

这里有两个字段发挥作用:

  • model 选择 gpt-6-sol,这样同一个端点以后也可以服务其他模型。
  • messages 是按顺序排列的对话轮次列表。每个条目都有一个 role(system、user 或 assistant)和一个 content 字符串。

安全默认值与可选附加项

将 model 和 messages 视为必需项。其他所有内容都是可选的,应有意识地添加:

  • 放在 messages 首位的 system 消息用于设定对话的行为或语气。这是一条普通消息,而不是单独的顶层字段。
  • 如果需要,输出长度控制作为请求体中的参数设置。只有当默认输出对你的用例来说太短或太长时,才添加它们。
  • 采样类参数改变的是输出形态,而不是有效性。在调试失败的调用时避免更改它们,因为它们无法修复身份验证或请求体结构错误。

一条实用规则

当出现失败时,请求负载应尽可能接近最小示例。逐个移除可选字段,直到调用成功,然后再重新添加它们。这样可以快速隔离问题:一个坏参数比一个埋在五个好参数中的坏参数更容易找到。

使用 curl 发送一次可用的请求

以下是一条完整的命令,只要你的密钥已导出,就可以直接运行。它使用了一个符合上述 HiAPI API 约定的占位端点路径。

curl -sS -X POST "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "user", "content": "用一句话解释什么是 API bearer token。" }
    ]
  }'

将 HIAPI_BASE_URL 设置为你 HiAPI 仪表盘中的基础端点。这些标志很重要:

  • -X POST 设置方法;这些调用都是 POST。
  • -H 添加每个请求头,每行一个。
  • -d 提供 JSON 请求体。单引号可以防止它被 shell 插值。
  • -sS 保持输出安静,但仍会显示错误,这正是脚本化时需要的。

读取响应

成功的响应是 JSON。你通常会看到一个顶层对象,包含模型名称和一个 choices 列表,每个 choice 都有一条消息,其 content 保存生成的文本。先读取结构再读取正文:确认对象能够解析,然后定位 content 字段。

为了提高可读性,可以管道传递给 JSON 格式化工具:

... | python -m json.tool

如果你的终端反而打印了一个错误对象,那么调用没有成功——请跳到错误部分,而不是调整提示词。当请求根本没有到达模型时,问题不在提示词。

用 Python 发送同样的请求

你刚刚在 curl 中验证过的请求负载可以直接迁移过来。保持请求体完全一致,这样在终端中验证过的修复也能在代码中应用。

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-6-sol",
    "messages": [
        {"role": "user", "content": "用一句话解释什么是 API bearer token。"}
    ],
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/chat/completions",
    headers=headers,
    json=payload,
    timeout=60,
)

response.raise_for_status()
data = response.json()

for choice in data.get("choices", []):
    message = choice.get("message", {})
    print(message.get("content", ""))

为什么这个版本在应用代码中更安全

  • 请求体是一个字典。 当你传入 json=payload 时,requests 会将其序列化并为你设置内容类型,但保留显式请求头可以避免切换客户端时出现意外。
  • 密钥来自环境变量。 没有任何秘密被硬编码,因此该文件可以提交。
  • raise_for_status() 先执行。 非 2xx 响应会立即抛出异常,在你尝试读取错误响应体中不存在的字段之前。
  • 设置了超时。 如果没有超时,停滞的连接可能会无限期挂起一个工作进程。

遍历 choices 的循环也防止了键缺失,这使得示例能够容忍包含很少或没有输出的响应。围绕这个骨架构建你的生产包装:验证、发送、检查状态,然后解析。

流式接收响应而不是等待

默认情况下,API 会在单个 JSON 响应中返回完整答案。对于长输出或交互式界面,你可以改为请求在生成过程中逐步交付响应。

流式开关

流式传输通过请求体标志启用,而不是使用不同的端点:

{
  "model": "gpt-6-sol",
  "messages": [
    { "role": "user", "content": "写一段关于 HTTP 状态码的简短文字。" }
  ],
  "stream": true
}

在非流式调用已经可用之后,最后再添加这个标志。它改变的是响应的组织方式,而不是请求是否有效。

消费增量输出

开启流式传输后,响应不再是单个 JSON 文档。它以一系列事件的形式到达,通常是按行分隔的,每个事件携带一小段输出。你的客户端必须在它们到达时读取,而不是对整个响应体调用 .json()。

with requests.post(
    f"{base_url}/chat/completions",
    headers=headers,
    json=payload,
    stream=True,
    timeout=60,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line.decode("utf-8"))

在终端中,同一个开关的行为与非流式调用不同:输出会逐步出现,因此被截断的管道可能看起来像失败的请求,而实际上只是流被中断了。

该用哪一种

对于批处理任务、测试以及任何需要一次性获得完整对象的情况,使用非流式。当有人正在等待文本,或者输出长到延迟明显时,使用流式。在代码库中保留两条路径,因为非流式路径更容易调试。

读取并修复常见错误码

先按状态码诊断,再按响应体诊断。在你确定哪一层失败之前,不要更改模型或重写提示词。

401 Unauthorized

原因: 密钥缺失、格式错误或已撤销。修复: 确认请求头准确写为 Authorization: Bearer <key>,检查是否有隐藏的空白字符或过期的环境变量,并验证密钥在你的仪表盘中仍然有效。打印变量的长度而不是值,以捕捉空变量错误。

400 Bad Request

原因: 请求体无法解析或缺少必需字段。修复: 再次发送最小请求负载,只包含 model 和 messages。在发送前用 python -m json.tool 验证 JSON;尾随逗号或 model 中的拼写错误是常见原因。确认 Content-Type 为 application/json。

403 Forbidden

原因: 密钥有效,但缺少对请求资源的访问权限。修复: 检查你的账户是否有权访问 gpt-6-sol,以及请求体中的模型名称是否与你的账户所配置的相符。

404 Not Found

原因: URL 路径错误,通常是端点拼写错误,或者基础路径缺失或重复。修复: 将完整 URL 与可用的 curl 调用逐字符对比。

429 Too Many Requests

原因: 你发送请求的速度超过了账户允许的范围。修复: 退避并以递增延迟重试。遵守响应头中的任何重试指导,切勿在循环中紧密重试——那会让问题更糟。将此与 5xx 区分开来,后者表示服务端问题,而不是你的请求速率问题。

5xx 服务器错误

原因: 服务无法处理一个原本有效的请求。修复: 用退避重试;如果问题持续,捕获响应体和请求 ID,并避免更改请求负载,因为它已经可用。

可重复的调试顺序

  1. 状态码——是身份验证、路径还是请求体问题?
  2. 响应体——它是否指出了有问题的字段?
  3. 请求负载结构——回到最小示例。
  4. 最后才考虑提示词或参数。

这个顺序能持续缩短从失败到修复的时间。一旦你的调用稳定下来,将可用的 curl 和 Python 版本并排保留,这样未来每次测试都从已知可用的状态开始。

立即开始构建持久 AI 产物

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

阅读 API 文档