# 认证 (https://hypit.ai/zh/api-reference/authentication/)

> 创建 API Key，用 Bearer 发送，并分清四种认证失败。

`/v1` 和 `/v1beta` 上的每一次调用，都用 hypit.ai 为你的账号签发的 API Key 认证。没有单独的
client id，不需要签名，除非你自己设置，否则也没有有效期。

## 拿到一把 Key [#拿到一把-key]

登录 [hypit.ai](https://hypit.ai)，打开账户面板，切到 **API Keys** 一栏。新建 Key 时明文只出现
一次——我们只存 SHA-256 摘要和前四位字符，所以丢了的 Key 找不回来，只能重新建一把。

一个账号最多同时持有 **50** 把有效 Key。

Key 长这样：

```text
sk-hh-x7Kq2mZ4nR8vT1wY6bC0dF3gH5jL9pQs
```

`sk-` 这个形状是刻意保留的，这样期待 OpenAI 风格密钥的工具链可以直接吃下它。中间的 `hh` 则是给
密钥扫描器、以及给读到一份粘贴配置的技术支持看的：一个项目里通常有十来个 `sk-` 开头的东西，这两
个字母能把 hypit.ai 的 Key 认出来。

<Callout type="warn" title="它就是一张不记名凭证">
  拿到 Key 的人就能花你的额度。请把它留在服务端，放进环境变量而不是写进源码；一旦怀疑泄漏，立刻
  在账户面板里删除——删除立即生效。
</Callout>

## 怎么发送 [#怎么发送]

标准写法是 `Authorization` 头：

```bash
curl https://hypit.ai/v1/models \
  -H "Authorization: Bearer $HYPIT_API_KEY"
```

因为不同厂商的 SDK 把凭据放在不同位置，每条路由都额外接受四种写法。按下表顺序读取，取第一个非空的：

| 位置                      | 例子                                |
| ----------------------- | --------------------------------- |
| `Authorization: Bearer` | `Authorization: Bearer sk-hh-...` |
| `X-Api-Key`             | Anthropic SDK 的写法                 |
| `X-Goog-Api-Key`        | Google GenAI SDK 的写法              |
| `Api-Key`               | 普通请求头                             |
| `?key=` 查询参数            | Google REST 的写法                   |

保留查询参数是为了让未经改造的 Google 客户端能直接访问
[Gemini 原生接口](/zh/api-reference/gemini)。其余场景一律优先用请求头：查询串会落进浏览器历史、
代理日志和 `Referer`。

## 每个响应都可追踪 [#每个响应都可追踪]

每个响应都带 `X-Request-Id`。如果你自己带了这个头（不超过 128 字符、不含换行），我们会沿用它，
这样你的日志和我们的日志指的是同一次请求。提工单时请附上它。

```bash
curl -i https://hypit.ai/v1/models \
  -H "Authorization: Bearer $HYPIT_API_KEY" \
  -H "X-Request-Id: my-trace-0001"
```

## 认证失败 [#认证失败]

全部是 HTTP `401`、`"type": "authentication_error"`，但 `code` 会告诉你该动哪个开关：

```json
{
  "error": {
    "message": "invalid api key",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}
```

| `code`                 | 含义                       |
| ---------------------- | ------------------------ |
| `missing_token`        | 五个位置里都没找到凭据              |
| `invalid_api_key`      | 这把 Key 不存在——通常是粘贴时截断了    |
| `key_disabled`         | 这把 Key 已在账户面板里禁用         |
| `key_expired`          | 这把 Key 设置了有效期并且已过期       |
| `account_disabled`     | 所属账号已被停用                 |
| `identity_unavailable` | HTTP `503`，账号目录短暂不可读，请重试 |

`401` 永远不表示「额度不够」——那是 `402`，见[额度与计费](/zh/api-reference/billing)。

## 第三方 Agent [#第三方-agent]

如果你在做一个替**别人的** hypit.ai 账号干活的应用，不要去要对方的 API Key。hypit.ai 自带一台
OAuth 2.0 授权服务器，用它签发的 access token 在 `/v1` 上和 Key 一样能用，但按模态分 scope——一个
只被授权做图片描述的 Agent，没法拿去烧掉一个月的视频额度。需要注册 client 请联系我们。