教程
如何通过 HiAPI API 调用 claude-opus-5-5@aws:curl 与 Python 指南
本页内容
通过 HiAPI 使用 claude-opus-5-5@aws 是什么样子
HiAPI 为多种模型提供统一的 HTTP 接口。你无需为每个提供商单独配置账号、SDK 和凭证存储,只需面向 HiAPI 使用同一种请求格式,并通过模型标识符选择所需模型。本教程中该标识符为 claude-opus-5-5@aws——@aws 后缀是模型名称的一部分,并非独立字段,应原样传入。
一次请求的生命周期如下:
- 身份验证——在
Authorization请求头中以 bearer token 形式发送你的 HiAPI API 密钥。 - 发送聊天式载荷——一个包含
model和messages数组的 JSON 请求体,每条消息包含role(system、user或assistant)和content。 - 接收 JSON 响应——助手的回复出现在响应的
choices数组中,并附带用量元数据。 - 继续对话——将助手消息和你的下一条用户消息追加到同一个
messages数组中,再次发送。该 API 是无状态的;完整对话保存在你的请求载荷中。
由于各模型的请求结构一致,你为 claude-opus-5-5@aws 编写的代码只需更改 model 字符串即可迁移到其他模型。请将该字段集中放在代码中的一处——如配置值或环境变量——而不是在多个文件中硬编码。
关于命名的一点说明:平台将该模型文档化为 claude-opus-5-5@aws。请使用这一确切字符串。拼写错误、多余空格或遗漏后缀将产生模型未找到类错误,而不会给出有用的警告。
获取凭证并完成身份验证
调用 API 之前,你需要从 HiAPI 账户获取一个 API 密钥。请将该密钥视为机密:存储在环境变量或平台的密钥管理器中,绝不要放入源代码管理,也绝不要放入发往浏览器的客户端代码中。
HiAPI 通过 Authorization 请求头中的 bearer token 对请求进行身份验证:
export HIAPI_API_KEY="your-api-key-here"
每个请求都必须包含:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
以下几条实用规则可避免大多数身份验证失败:
- 保留字面量
Bearer前缀,后跟一个空格,然后是密钥。缺少前缀或空格是常见的复制粘贴错误。 - 不要在请求头值中给密钥加引号。
- 如果轮换密钥,请更新环境变量并重启进程——长时间运行的 worker 常会缓存旧值。
- 将密钥粘贴到
.env文件时检查尾部空白或换行符;某些加载器不会自动去除。
如果密钥缺失或格式错误,你会收到身份验证错误(401 类),而非模型错误,因此很容易与后续问题区分开来。一旦请求成功通过身份验证,同一请求头即可用于流式传输、工具调用以及本指南中的其他所有模式——你无需为每个功能使用不同的凭证。
对于服务端代码,在启动时加载一次密钥,并将其传入共享客户端或一个小型包装函数。这样可将机密集中在一处,并使开发凭证与生产凭证之间的切换变得轻而易举。
用 curl 构建可运行的请求
以下是一个完整、可运行的请求。将占位密钥替换为你自己的密钥,或先运行上一节的 export,让 shell 进行替换。
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-5-5@aws",
"messages": [
{
"role": "user",
"content": "用三句话解释为什么幂等 POST 端点对支付 API 很重要。"
}
]
}'
逐项拆解:
- 端点——
POST https://api.hiapi.ai/v1/chat/completions。 - 请求头——bearer token 和 JSON 内容类型。两者均为必需。
model——确切标识符claude-opus-5-5@aws。messages——由 role 和 content 对象组成的数组。最后一条用户消息是模型要回应的内容。- 载荷——
-d发送原始 JSON,因此引号处理很重要。在 shell 中用单引号包裹整个请求体,JSON 键使用双引号。
响应是一个包含 choices 数组的 JSON。生成的文本位于 choices[0].message.content,并包含用量信息(token 计数),以便你监控消耗。响应用量按 token 计费,当前费率见网站的价格面板。
常见调整:
{
"model": "claude-opus-5-5@aws",
"max_tokens": 512,
"temperature": 0.2,
"messages": [
{"role": "system", "content": "你是一名简洁的技术编辑。"},
{"role": "user", "content": "用一行总结上面的请求体。"}
]
}
使用 max_tokens 限制失控的生成,用 temperature 控制冗长度和方差,用 system 消息为每段对话设定一次行为。system 消息应放在同一个 messages 数组中,位于用户轮次之前。
Python 中的同一请求
Python 版本使用标准库的 urllib,因此该代码片段无需安装任何东西即可运行。如果你更偏好客户端库,请求结构完全相同——只是传输方式不同。
import json
import os
import urllib.request
API_URL = "https://api.hiapi.ai/v1/chat/completions"
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "claude-opus-5-5@aws"
def ask(user_message: str, system_message: str | None = None) -> str:
messages = []
if system_message:
messages.append({"role": "system", "content": system_message})
messages.append({"role": "user", "content": user_message})
payload = json.dumps({
"model": MODEL,
"messages": messages,
}).encode("utf-8")
request = urllib.request.Request(
API_URL,
data=payload,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
body = json.loads(response.read().decode("utf-8"))
return body["choices"][0]["message"]["content"]
if __name__ == "__main__":
print(ask("用恰好五个词打招呼。"))
为什么这种结构值得保留:
MODEL和API_URL是模块级常量,因此切换模型或端点只需改一行。- 密钥来自环境;函数从不接受原始机密参数。
- 解析逻辑隔离在末尾,因此你可以将
urllib换成httpx或requests,而无需改动对话构建方式。
要继续多轮对话,在再次发送前将助手的回复和下一条用户消息追加到 messages 中。让数组持续增长,直到触及上下文限制,然后将较早的轮次总结为一条 system 消息以保持在预算内。响应中的用量基于 token,当前费率列在网站的价格面板上。
用于交互场景的流式响应
对于聊天 UI 和长时间生成,流式传输会在输出产生时即发送部分内容,而不是等待完整响应。请求体除一个字段外保持不变:
{
"model": "claude-opus-5-5@aws",
"messages": [{"role": "user", "content": "为一个刚刚采用流式传输的库写一段简短的变更日志。"}],
"stream": true
}
当 stream: true 时,端点以服务器发送事件(server-sent events)响应:每个块是一行以 data: 为前缀的内容,流以一行最终的终止标记结束。大多数块在 choices 数组中包含一个带有文本片段的 delta,而非完整消息。
使用 curl 时,去掉 -sS 的静默效果,观察输出逐步到达:
curl -N https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"claude-opus-5-5@aws","stream":true,"messages":[{"role":"user","content":"慢慢地数到五。"}]}'
-N 标志禁用缓冲,以便你在块到达时看到它们。在 Python 中,逐行读取响应:
with urllib.request.urlopen(request) as response:
for raw_line in response:
line = raw_line.decode("utf-8").strip()
if not line.startswith("data: "):
continue
data = line[len("data: "):]
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0].get("delta", {})
text = delta.get("content")
if text:
print(text, end="", flush=True)
实用提示:
- 始终处理
[DONE]终止标记和空行/保活行;不要假设每一行都是 JSON。 - 绝不要让 UI 线程阻塞在整个流上——在 delta 到达时将其追加到缓冲区。
- 如果客户端断开连接,请关闭响应,以便释放上游生成。
- 流式传输不会改变用量的计算方式;最后一个块通常携带用量元数据。计费按输出 token 计算,当前费率见网站的价格面板。
向对话中添加工具调用
工具使用让模型可以从你的代码中请求结构化操作,而不仅仅是生成文字。请求中增加一个 tools 数组;对话中增加携带 tool_calls 的助手消息和携带结果的 role: "tool" 消息。
使用 JSON Schema 定义工具的参数:
{
"model": "claude-opus-5-5@aws",
"messages": [
{"role": "user", "content": "里斯本现在的天气怎么样?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "返回某城市的当前天气。",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称,例如 Lisbon"}
},
"required": ["city"]
}
}
}
]
}
模型可能返回包含 tool_calls 的消息,而非最终文本。每个条目指定函数名并携带一个 JSON 字符串形式的参数。你的工作是针对自己的系统执行该函数,然后追加结果:
- 将包含
tool_calls的助手消息原样追加到messages。 - 为每个调用追加一条消息,包含
role: "tool"、助手消息中匹配的tool_call_id,以及设置为序列化结果的content。 - 使用相同的
tools数组再次发送请求。模型随后会基于你的结果生成自然语言回答。
值得尽早建立的防护措施:
- 验证参数——在执行任何操作之前,依据 schema 验证参数——绝不要将模型输出直接传入 shell 或数据库查询。
- 限制循环。 为工具调用轮次设置上限(通常三到五轮),以免持续请求调用的模型无限循环。
- 将错误作为工具结果返回。 如果函数失败,请发送一条简短的错误字符串并附带匹配的
tool_call_id;模型随后可以重试或解释失败原因,而不是停滞。 - 保持工具描述精确。 描述模糊导致工具选择错误的频率远高于参数错误。
工具定义随请求一起评估,并计入你的 token 用量。当前费率发布在网站的价格面板上。
接下来做什么
从最小的 curl 调用开始,将其移入 Python 包装函数,然后仅在你的用例需要时才叠加流式传输和工具。模型字符串 claude-opus-5-5@aws 始终不变——其他一切都是请求载荷中的字段。