我拿到了一个 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 的固定阈值或 temporary block 拒绝了请求。查看错误详情：成本/单请求 Token 超限要调整请求或策略，临时封禁则等待 TTL 或联系管理员；不要立即盲重试
429	限流或并发拒绝	见认证、请求头与错误，不同成因处理方式不同

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

文档不能只凭别名回答这个问题：v0.9.0 的 GET /v1/models 只列出公开别名，不返回能力；需同时有 inference 和 discovery。见模型发现。一个 Route 还可能包含多个 Deployment，并分别绑定不同的 Provider Profile。字段是否可用取决于本次请求经过能力过滤后剩余的 eligible targets，而不是从别名推断出一个固定 Profile。

不必干等，有三条路：

直接试。发一个最小的带 tools 的请求。不支持时会在到达上游之前就被拒（400），不会产生费用，也不会有半截响应。
问管理员一个具体问题：「别名 chat 当前有哪些 eligible Deployment/Profile，带 tools 时会剩下哪些，是否允许 fallback？」再用 Chat Completions 页按每个 Profile 核对限制。
写降级路径。按第 1 条的错误码判断，不支持时退回不带工具的调用，而不是让整个请求挂掉。

Project、Key 和 Route 在多环境中的完整划分方式见最佳实践案例库。