教程
如何通过 HiAPI API 使用 gpt-6-sol:curl、Python 与一次可用的请求
本页内容
首次调用之前需要准备什么
在写任何代码之前,先准备好三样东西。本教程的其余内容都以此为基础。
一个 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,并避免更改请求负载,因为它已经可用。
可重复的调试顺序
- 状态码——是身份验证、路径还是请求体问题?
- 响应体——它是否指出了有问题的字段?
- 请求负载结构——回到最小示例。
- 最后才考虑提示词或参数。
这个顺序能持续缩短从失败到修复的时间。一旦你的调用稳定下来,将可用的 curl 和 Python 版本并排保留,这样未来每次测试都从已知可用的状态开始。