# API 接入指南

更新日期：2026-10-29。面向使用客户端或代码调用模型的客户。

## 客户端快速接入

支持自定义 OpenAI 兼容接口的客户端，填好接入地址、API Key 和模型名称即可接入，无需编写代码，也无需先执行“获取模型列表”命令。

| 客户端里的字段 | 填写内容 |
| --- | --- |
| URL / Base URL / 接口地址 | `https://hailqiv.cn/v1` |
| API Key / 密钥 | 在客户控制台创建密钥，保存首次显示的完整 API Key |
| 模型名称 / Model ID | 从下方“可调用模型”中复制完整模型名称，例如 `claude-haiku-5-5` |

1. 打开客户控制台 `https://hailqiv.cn/`。首次使用须通过 QQ 邮箱（`@qq.com`）接收验证码、设置密码并注册；已有 QQ 邮箱账号使用邮箱和密码登录。
2. 新注册账号余额为 0，且没有 API Key。在“API Key”区域填写名称并点击“创建 API Key”，保存弹窗中的完整 Key。每个账号最多同时保留 5 个。
3. 确认账户状态和可用余额。完整 Key 仅在创建时显示一次，之后列表只显示脱敏内容；遗失时可删除旧 Key 并创建新 Key。
4. 在客户端添加自定义服务；有协议选项时，选择 OpenAI 兼容 / Chat Completions，再填入上面的三项内容。
5. 保存配置，选中该服务与模型，即可开始对话；可先发送一条简短消息确认接入。

QQ 邮箱和密码用于登录控制台、查看账单及管理密钥；API Key 仅用于模型调用。删除最后一个 Key 不影响邮箱登录。Key 输入框只填完整 Key，不要填写邮箱密码，也不要自行加上 Bearer。

## 可调用模型

直接复制右列的完整模型名称，粘贴到客户端的模型输入框。名称中的大小写、数字、点和连字符请保持原样。

| 模型 | 模型名称（填写此项） |
| --- | --- |
| Claude Opus 5.5 | `claude-opus-5-5` |
| Claude Fable 5.1 | `claude-fable-5-1` |
| Claude Sonnet 5.5 | `claude-sonnet-5-5` |
| Claude Haiku 5.5 | `claude-haiku-5-5` |
| GPT-6 Astra | `gpt-6-astra` |
| GPT-6.1 Sol | `gpt-6.1-sol` |
| GPT-6 Luna | `gpt-6-luna` |
| Grok 4.7 | `grok-4.7` |

以上为 2026-10-28 核对的开放模型。开放情况如有调整，以客户控制台的当前列表为准；高级用户也可使用文末的模型列表接口查询。

## 常用配置与注意事项

### 地址怎么填

通常使用以 `/v1` 结尾的接入地址，客户端会自动补全调用路径。只有字段明确要求“完整聊天接口地址”时，才填写 `https://hailqiv.cn/v1/chat/completions`，避免出现重复的 `/v1/v1` 或 `/chat/completions`。

### 模型怎么选

模型名称直接使用上表中的完整名称，不要把展示名（如 Claude Opus 5.5）当成调用名称。一个客户端中可添加多个模型，使用时确认当前选中的服务和模型。

无需手动添加前缀；客户端自动附加的 `custom-local:` 冒号前缀可兼容，前缀后仍须是有效的完整模型名称。

### 工具、图片与思考模式

首次接入可先保留默认参数，使用普通文本对话，再按需要开启工具调用、图片输入和思考模式。这些能力取决于具体模型与客户端，不能只凭客户端显示了开关判断是否支持。

若客户端使用 Messages 协议，基础地址一般填 `https://hailqiv.cn`，完整接口为 `https://hailqiv.cn/v1/messages`。常规 OpenAI 兼容配置使用上面的 `/v1` 地址即可。

“测试连接”若实际发送了模型请求，会产生相应用量。直接填写模型名称即可使用；不必为接入反复点击测试。

## 费用与用量

- 模型不同，可用参数可能不同。部分 GPT 模型需要用 `max_completion_tokens` 替代 `max_tokens`，不要同时传这两个参数；遇到参数错误时先删掉非必要选项。
- 思考模型的输出额度可能包含推理用量。额度过低时可能正文为空；正文为空不代表没有用量。请给出合理额度，并查看用量明细。
- 输入与输出分别计费，金额单位为美元，按账户适用售价结算。Token 不等于字符数；历史对话和工具定义也可能增加输入用量。
- 请求处理中可能暂时占用部分可用余额，请求结束后结算。余额不足时，请减少上下文或输出额度，或补充余额。
- 登录控制台可核对余额、模型、输入 / 输出 token、扣费、状态和时间。需要充值时按控制台提示操作；生成订单不等于完成支付或到账。
- 请求超时或断流后，先查使用记录再决定是否重试；重复发送可能产生多次用量。首次接入建议关闭自动重试，设置合理的输出上限。

## 常见问题

| 现象 / HTTP 状态 | 建议处理 |
| --- | --- |
| 客户控制台能登录，客户端却不能调用 | 账号密码与 API Key 不同；确认填的是 Key，并检查协议、Base URL 和模型名 |
| 400 或参数错误 | 检查 JSON、消息格式、模型支持的参数；先关闭思考、图片、工具等附加功能 |
| 401 | 检查 Key 是否完整、有无空格；代码使用 `Authorization: Bearer YOUR_API_KEY`，客户端 Key 输入框通常只填 Key |
| 402 | 检查可用余额及本次输出上限，补充余额后重试 |
| 403 | 检查账户状态或权限，联系服务方核实 |
| 404 | 核对接口路径及模型 `id`，从上方模型表重新复制完整名称，必要时查询当前模型列表；部分参数错误也可能返回此状态，请同时看错误说明 |
| 429 | 请求过于频繁或被限流，降低并发，按提示等待后重试 |
| 5xx、超时、断流 | 稍后重试；持续发生时提供时间、客户端版本、模型、状态码与脱敏错误信息 |
| 连不上或一直转圈 | 使用完整的协议、地址和端口；检查本地代理是否影响此地址，可换网络对比 |
| 有用量但没有正文 | 检查思考 / 输出额度、工具调用结果及流式解析，勿连续重复点击测试 |

错误说明与状态码需一起看，不要只按一个状态码判断原因。请求支持时无需提供完整 Key、账号密码或完整私人对话。

## 密钥与使用安全

- 建议按客户端或设备分别创建密钥，用名称区分用途。删除密钥后，新的调用将无法通过身份验证；进行中的请求仍可能完成并结算。
- 邮箱验证码 5 分钟内有效，同一邮箱 60 秒内不能重复获取，输错过多须重新获取。验证码和密码均不要提供给他人。

- Key 具有调用和访问账户信息的权限。不要写进公开网页、前端项目、代码仓库、聊天截图或分享文档。
- 每位使用者使用独立账号和 Key。怀疑泄露时，立即联系服务方停用旧 Key 并更换凭证。
- 若当前接入地址为 HTTP，传输不加密，请仅作非敏感测试；涉及敏感内容时使用服务方提供的 HTTPS 地址。
- 本文中的 `YOUR_API_KEY` 均为占位符，文档不会自动填入或保存你的真实 Key。

## 代码调用示例（进阶）

仅供自行编程接入时参考；使用客户端的客户无需执行本节代码。

以下使用 `claude-haiku-5-5` 演示。请先确认它在可用列表中，否则替换为当前可用模型。运行聊天示例会产生实际用量。

### cURL

```bash
curl "https://hailqiv.cn/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-5-5",
    "messages": [{"role": "user", "content": "请简短介绍一下你自己"}],
    "max_tokens": 256,
    "stream": false
  }'
```

### Windows PowerShell

先在当前终端设置环境变量，再执行请求。不要把真实 Key 写入公开脚本或截图。

```powershell
$env:API_KEY = 'YOUR_API_KEY'
$body = @{
  model = 'claude-haiku-5-5'
  messages = @(@{ role = 'user'; content = '你好，请简短回复' })
  max_tokens = 256
} | ConvertTo-Json -Depth 6

$result = Invoke-RestMethod `
  -Uri 'https://hailqiv.cn/v1/chat/completions' `
  -Method Post `
  -Headers @{ Authorization = "Bearer $env:API_KEY" } `
  -ContentType 'application/json; charset=utf-8' `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

$result.choices[0].message.content
```

### Python

安装 `openai` 包：`python -m pip install openai`。在运行环境中设置 `API_KEY` 后执行：

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["API_KEY"],
    base_url="https://hailqiv.cn/v1",
    max_retries=0,
    timeout=120.0,
)

response = client.chat.completions.create(
    model="claude-haiku-5-5",
    messages=[{"role": "user", "content": "你好，请简短回复"}],
    max_tokens=256,
)
print(response.choices[0].message.content)
```

需要逐字显示时，在同一 `client` 上使用流式调用：

```python
stream = client.chat.completions.create(
    model="claude-haiku-5-5",
    messages=[{"role": "user", "content": "写一句问候语"}],
    max_tokens=256,
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        text = chunk.choices[0].delta.content
        if text:
            print(text, end="", flush=True)
print()
```

聊天内容通常在 `choices[0].message.content`；流式文本在 `choices[0].delta.content`。流式数据可能包含没有 `choices` 的用量块，处理时应检查字段，不要将它当作错误。

### Messages 协议

需要 Messages 格式时，客户端的基础地址填 `https://hailqiv.cn`；完整端点为 `https://hailqiv.cn/v1/messages`。鉴权使用 `x-api-key`，并按客户端要求提供版本头。请选择支持此协议的模型。

```bash
curl "https://hailqiv.cn/v1/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-5-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "你好，请简短回复"}]
  }'
```

## 获取模型列表（进阶）

客户端支持“获取模型”或“刷新模型列表”时，也可直接使用该功能。下面的接口查询供开发者参考，不是接入前的必做步骤；查询模型列表本身不调用模型，不产生模型 token 费用。

将 `YOUR_API_KEY` 替换为你自己的 Key。以下为 macOS / Linux / Git Bash 的 cURL 写法；Windows PowerShell 可使用后面的示例。

```bash
curl "https://hailqiv.cn/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

在返回的 `data` 数组里读取每一项的 `id`。模型开放情况可能调整，以你请求时返回的列表为准。