我拿到了一个 Key

这一页面向只有一个 Gateway Key 和一个模型别名的应用开发者。你不需要访问 Halro 控制台，也不需要知道它背后连的是哪家上游服务商 —— 那正是网关要替你隐藏的东西。

你手上需要三样东西

东西	长什么样	从哪来
实例地址	例如 `https://halro.your-company.internal`	必须问管理员。Halro 是自托管的，没有固定域名，地址不写在 Key 里
Gateway Key	`gw_` 开头，其后 43 个字符	管理员在控制台创建后一次性交给你，之后无法再次查看
模型别名	一个普通名字，例如 `chat`	管理员定义的 Route。它不是上游模型标识

本页示例统一写 https://halro.example.com，你要把它换成上面第一行那个地址。

先把 Key 放进环境变量

不要把 Key 写进 shell history：

read -r -s HALRO_GATEWAY_KEY
printf '\n'
export HALRO_GATEWAY_KEY

用完清除：

unset HALRO_GATEWAY_KEY

第一个请求

curl https://halro.example.com/v1/chat/completions \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "你好，请用一句话介绍 Halro"}
    ]
  }'

显式给出输出上限是值得的：它既限制上游输出，也限制网络结果不明确时的保守预算上界。这里用 max_tokens 而不是 max_completion_tokens —— 后者在 DeepSeek 那条链路上被声明为不支持，而你无法从别名判断自己落在哪条链路上（见下）。

你最可能先撞上的几种失败

状态	code	含义
401	`invalid_api_key`	Key 缺失、无效、已吊销，或格式不对（是 `gw_` + 43 字符，别按 16 位截断）
404	`model_not_found`	这个别名没有对应的 Route
403	`model_not_allowed`	Route 存在，但你的 Project 没有被授权用它
400	`unsupported_feature`	别名存在，但它不支持你调用的这类操作
503	`provider_unavailable`	这个别名下没有健康的 Deployment，稍后重试
403	`token_guard_blocked`	本次请求的预估价格超出 Token Guard 上限。重试没有用
429	七种之一	见认证、请求头与错误，不同成因处理方式不同

「我的别名支持工具调用吗？」

文档回答不了这个问题：Halro 的 Gateway 不实现 GET /v1/models，而字段支持情况取决于你的别名解析到哪个 Provider Profile —— 那是管理员侧的配置。

不必干等，有三条路：

直接试。发一个最小的带 tools 的请求。不支持时会在到达上游之前就被拒（400），不会产生费用，也不会有半截响应。
问管理员一个具体问题：「我的别名 chat 对应哪个 Provider Profile？」拿到 Profile 名字之后，Chat Completions 页的字段表按 Profile 逐列列出了限制，你自己就能查。
写降级路径。按第 1 条的错误码判断，不支持时退回不带工具的调用，而不是让整个请求挂掉。