API 接入指南

01客户端快速接入

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

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。

02可调用模型

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

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

03常用配置与注意事项

地址怎么填

通常使用以 /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 地址即可。

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

04费用与用量

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

05常见问题

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

06密钥与使用安全

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

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

07代码调用示例（进阶）

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
  }'

$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

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)

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()

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": "你好，请简短回复"}]
  }'

08获取模型列表（进阶）

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