博客

教程

如何通过 HiAPI API 调用 claude-opus-5-5@aws:curl 与 Python 指南

2026年11月12日
封面图案:近黑色背景上散布薄荷绿的半色调圆点,密度呈渐变效果,并带有深青色的点缀。
本页内容

通过 HiAPI 使用 claude-opus-5-5@aws 是什么样子

HiAPI 为多种模型提供统一的 HTTP 接口。你无需为每个提供商单独配置账号、SDK 和凭证存储,只需面向 HiAPI 使用同一种请求格式,并通过模型标识符选择所需模型。本教程中该标识符为 claude-opus-5-5@aws——@aws 后缀是模型名称的一部分,并非独立字段,应原样传入。

一次请求的生命周期如下:

  1. 身份验证——在 Authorization 请求头中以 bearer token 形式发送你的 HiAPI API 密钥。
  2. 发送聊天式载荷——一个包含 model 和 messages 数组的 JSON 请求体,每条消息包含 role(system、user 或 assistant)和 content。
  3. 接收 JSON 响应——助手的回复出现在响应的 choices 数组中,并附带用量元数据。
  4. 继续对话——将助手消息和你的下一条用户消息追加到同一个 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 字符串形式的参数。你的工作是针对自己的系统执行该函数,然后追加结果:

  1. 将包含 tool_calls 的助手消息原样追加到 messages。
  2. 为每个调用追加一条消息,包含 role: "tool"、助手消息中匹配的 tool_call_id,以及设置为序列化结果的 content。
  3. 使用相同的 tools 数组再次发送请求。模型随后会基于你的结果生成自然语言回答。

值得尽早建立的防护措施:

  • 验证参数——在执行任何操作之前,依据 schema 验证参数——绝不要将模型输出直接传入 shell 或数据库查询。
  • 限制循环。 为工具调用轮次设置上限(通常三到五轮),以免持续请求调用的模型无限循环。
  • 将错误作为工具结果返回。 如果函数失败,请发送一条简短的错误字符串并附带匹配的 tool_call_id;模型随后可以重试或解释失败原因,而不是停滞。
  • 保持工具描述精确。 描述模糊导致工具选择错误的频率远高于参数错误。

工具定义随请求一起评估,并计入你的 token 用量。当前费率发布在网站的价格面板上。

接下来做什么

从最小的 curl 调用开始,将其移入 Python 包装函数,然后仅在你的用例需要时才叠加流式传输和工具。模型字符串 claude-opus-5-5@aws 始终不变——其他一切都是请求载荷中的字段。

立即开始构建持久 AI 产物

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

阅读 API 文档