如何通过 HiAPI API 调用 gpt-5.6-terra@azure：curl 与 Python 指南

gpt-5.6-terra@azure 在 HiAPI 请求中的含义

在 HiAPI 请求中，gpt-5.6-terra@azure 是一个模型标识符——你需要把它放在聊天请求体的 model 字段里。这就是你这一侧的全部约定。你不需要构造服务商专属的 URL，不需要更换 SDK，也不需要改变请求体的结构。

@azure 后缀是路由元数据，它告诉 HiAPI 该模型的这个变体应由哪个后端来处理请求。请求体中的其他内容——messages、temperature、max_tokens、stream、tools——都保持你已熟悉的标准 chat-completions 结构。这在实践中很重要：如果你已经有一个在 HiAPI 上调用其他模型的可用请求，迁移到 gpt-5.6-terra@azure 通常只需改一行。

{
  "model": "gpt-5.6-terra@azure",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

养成两个习惯可以让模型 ID 相关的 bug 很少出现：

• 把 ID 当作不透明字符串。原样复制，包括 @ 和小写后缀。不要有空格，不要改变大小写。
• 把它放在配置里，而不是散落在代码各处。用一个常量或环境变量，可以让不同模型 ID 之间的 A/B 测试变成改配置，而不是重构。

由于后缀负责路由，你不应仅凭 ID 就推断底层服务栈的任何情况。延迟、限制和支持的参数都是 HiAPI 暴露该模型时所具备的属性，因此请先用一个小请求实际验证行为，再把假设写进你的应用。

前提条件与准备好密钥

在第一次调用之前，先确认三件事：

1. 一个 HiAPI 账户。你需要登录后才能创建凭证，并在控制台查看当前的模型与价格信息。
2. 一个 API 密钥。在控制台生成，并存放在安全的地方——把它当作密码对待。本指南不假设特定的密钥格式；控制台给你的任何字符串，就是放进 Authorization 头的值。
3. 一个 HTTP 客户端。用 curl 做快速验证，用 Python 3 搭配 requests 或 OpenAI 兼容 SDK 编写应用代码。

让密钥远离源文件

使用环境变量。这个模式在每个平台上都一样：

export HIAPI_API_KEY="your-key-here"

然后在运行时引用它。在 shell 中："$HIAPI_API_KEY"。在 Python 中：os.environ["HIAPI_API_KEY"]。在 CI 中，使用你的服务商提供的密钥存储，而不是提交一个 .env 文件。

如果你为了调试把密钥粘贴到终端里，请记住它可能会留在 shell 历史记录中——如果它是真实凭证，之后要轮换掉。对于本地开发，使用一个仅用于测试的一次性密钥，比复用生产凭证更容易管理。

确认你的 Base URL 和端点

HiAPI 提供 OpenAI 兼容的 chat completions 端点。从你的控制台文档中获取 base URL 和路径，并在 curl 和 Python 中保持一致——大多数“curl 能用但 Python 不行”的报告，归根结底都是尾随斜杠或缺少路径段。

一个可用的 curl 请求

下面是最小的正确调用。把 base URL 替换成你控制台中显示的那个，并确保 HIAPI_API_KEY 已导出。

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra@azure",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API gateway does in two sentences."}
    ],
    "max_tokens": 200
  }'

逐字段说明：

• -sS 会静默进度条，但仍显示错误。如果你希望响应头与响应体一起显示，加上 -i。
• Authorization: Bearer $HIAPI_API_KEY 用于认证请求。Bearer 前缀和空格都是必需的。
• Content-Type: application/json——如果省略，许多服务器会在解析请求体之前就将其拒绝。
• model——精确的 ID gpt-5.6-terra@azure。
• messages——有序数组。system 设定行为；user 承载提示词。多轮对话按顺序追加 assistant 和 user 轮次。
• max_tokens——响应长度的上限。快速验证时保持较小，这样失败成本低、速度快。

成功的响应是包含 choices 数组的 JSON；你需要的文本在 choices[0].message.content。前几次可以把输出通过 JSON 格式化工具处理，这样你能看到结构，而不是对着一长行费劲地看。

一旦这个请求能跑通，就把它保存为一个从环境变量读取密钥的 shell 脚本。这样你就有了一个可重复的健康检查，每当更改模型 ID 或参数时都可以运行。

等价的 Python 请求

请求体完全相同——只是传输方式变了。使用 requests：

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API gateway does in two sentences."},
    ],
    "max_tokens": 200,
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

有三个值得保留的细节：使用 json=payload 而不是手动序列化（它会替你设置请求头和编码），始终设置 timeout，并调用 raise_for_status()，这样 4xx 或 5xx 会以异常形式暴露，而不是在你索引错误响应体时抛出 IndexError。

服务商 SDK 风格

由于该端点与 OpenAI 兼容，配置了自定义 base URL 的 SDK 会产生相同的请求：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)

completion = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Say hello in one word."}],
    max_tokens=50,
)
print(completion.choices[0].message.content)

展示这两种方式的意义在于：模型 ID 是标识由哪个模型为你服务的唯一变量。其余都是普通的 chat-completions 管线，因此你可以在原始 HTTP 和 SDK 之间切换，而无需重写逻辑。

添加流式与工具调用

这两个功能都是增量式的。你不是在重写基础请求——而是添加字段并改变消费响应的方式。

流式

在请求体中设置 "stream": true：

stream = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Count from 1 to 10."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

响应变成一系列服务器发送事件，而不是单个 JSON 对象。每个块携带一个包含内容片段的 delta；在第一个和最后一个块上，delta.content 可能为 None，因此在拼接之前要做好判断。使用原始 HTTP 时同理——逐行读取响应体，去掉 data: 前缀，跳过 [DONE]，并解析每一行 JSON。

工具调用

在请求中描述工具，让模型决定何时调用它们：

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [{"role": "user", "content": "What's the weather in Berlin?"}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
    "tool_choice": "auto",
}

当模型想要调用工具时，choices[0].message 会包含一个 tool_calls 数组，而不是纯文本。每个条目都有一个 id 和一个 function，后者包含 name 和 arguments（一个你必须解析的 JSON 字符串）。执行你的函数，然后把结果作为一条 role: "tool" 的消息发回去，带上匹配的 tool_call_id 和序列化的输出——然后再发起一次请求以获取最终答案。

tool_choice 接受 "auto"（模型决定）、"none"（仅文本）或指定的函数。流式与工具可以组合使用，但工具调用参数会以片段形式跨块到达，你必须先累积再解析——请先把非流式的工具调用跑通。

排查常见请求错误

按以下顺序调试；每一步隔离一层，这样你就不会同时追两个问题。

1. 认证（401 / 403）

最可能的原因：密钥缺失、Bearer 前缀被丢掉，或环境变量展开为空字符串。在不打印完整密钥的情况下回显请求头的构造方式，并确认变量设置在运行请求的同一个 shell 或进程中。

2. 端点与路径（404）

404 通常意味着路径错误——拼写错误、缺少 /v1，或在本不该有的地方多了尾随斜杠。请从控制台复制确切的 URL，而不是重新输入。

3. 模型 ID（400，附带模型相关消息）

ID 必须完全匹配：gpt-5.6-terra@azure。常见的失误包括大小写变化、缺少 @azure，或复制粘贴带来的多余空格。如果消息说模型未知，先把配置的字符串与控制台列表逐字符比对，再怀疑服务故障。

4. 请求体格式错误（400 / 422）

如果错误提到请求体，先检查 JSON 有效性——尾随逗号或未转义的引号是常见元凶。然后核对字段名（是 messages，不是 message）和角色（system、user、assistant、tool）。max_tokens 必须是数字，tools 必须是结构正确的对象数组。

5. 将流式响应当作普通 JSON 处理

如果输出为空、乱码或抛出解析错误，你很可能请求了 stream: true，却把响应当作单个 JSON 文档来解析。请按事件流读取，跳过 [DONE]，并对 None delta 做防护。

6. 客户端超时

长时间生成可能超过默认的 HTTP 超时。在客户端显式调高它，或切换到流式，让字节立即开始到达。

快速复现检查清单

• 运行最小化的 curl 调用。如果成功，问题在你的代码里。
• 如果失败，在一个全新的 shell 中用你的密钥和模型 ID 重试。
• 同时记录 HTTP 状态码和响应体——错误响应体带有诊断细节。
• 只有在这些检查都通过之后，才应怀疑服务端问题值得升级处理。

有了可用的请求、流式循环和这份检查清单，gpt-5.6-terra@azure 在你技术栈中的表现就和其他聊天模型一样——而切换模型也变成了配置里的一行改动。