API GUIDE · AI 中转站 · OPENAI COMPATIBLE
HrioAI API 调用
指南
HrioAI(HrioAPI 狐一狐API)是一个 AI API 中转站,对外提供兼容 OpenAI 协议的接口。如果你已经会调 OpenAI,那你在 HrioAI 上要做的事只有两件:换 base_url,换 api_key。下面从创建 Key 到排查报错,一次讲完。
鉴权 Bearer Token
协议 OpenAI 兼容接口
流式 stream=true 走 SSE
调试 控制台内在线调试台
ON THIS PAGE
本页内容
STEP 01
第一步:拿两个值
- 接口地址(Base URL)登录控制台后,在「API 令牌」页面可以复制到当前推荐的接口地址,形如 https://<接口域名>/v1。请以控制台显示的为准,不要照抄第三方教程里的地址。
- API Key在「API 令牌」页面新建,Key 只在创建时完整显示一次,请立即保存。建议按用途分别建 Key,方便单独限额和排查。
- 模型 ID在「模型定价」页面复制准确的模型 ID,填到请求体的 model 字段里。模型可用范围取决于你所在的分组。
安全习惯:Key 只放在服务端或本地配置里,不要写进前端代码、不要提交到公开仓库。一旦泄露,删除并重建一个新的即可。
STEP 02
第二步:发起一次调用
curl https://<你的接口地址>/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <你的 API Key>" \
-d '{
"model": "<控制台里的模型 ID>",
"messages": [
{ "role": "user", "content": "用一句话解释什么是 API 网关" }
],
"stream": false
}'
Python · 官方 OpenAI SDK
from openai import OpenAI
client = OpenAI(
base_url="https://<你的接口地址>/v1", # 换成 HrioAI 的地址
api_key="<你的 API Key>",
)
resp = client.chat.completions.create(
model="<控制台里的模型 ID>",
messages=[{"role": "user", "content": "你好,介绍一下你自己"}],
)
print(resp.choices[0].message.content)
JavaScript / Node
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://<你的接口地址>/v1",
apiKey: process.env.HRIO_API_KEY,
});
const resp = await client.chat.completions.create({
model: "<控制台里的模型 ID>",
messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);
STEP 03
第三步:换成流式输出(可选)
把 stream 设为 true 就得到 SSE 流式响应,适合聊天界面逐字显示。
stream = client.chat.completions.create(
model="<模型 ID>",
messages=[{"role": "user", "content": "写一首短诗"}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
MULTIMODAL
图片与视频模型
图像、视频类模型大多不是「一问一答」,而是「提交任务 → 拿结果」,控制台里会显示每次任务的进度与最终产物。
建议先在控制台的调试页把参数跑通,再照抄成代码。不同模型的入参差异较大,具体字段以控制台调试页给出的请求样本为准。
TROUBLESHOOTING
常见错误与排查
| 现象 | 常见原因 | 怎么处理 |
|---|---|---|
| 401 / 鉴权失败 | Key 填错、多了空格、Key 已被删除 | 重新复制 Key;必要时在控制台新建一个 |
| 404 / 找不到接口 | base_url 少写或多写了 /v1 | 直接复制控制台「API 令牌」页里的地址 |
| 模型不存在 | 模型 ID 拼写不对,或该分组不可用 | 在「模型定价」页复制准确的模型 ID |
| 余额或额度不足 | 账户余额用完,或这个 Key 的额度上限到了 | 在账单页充值,或调整该 Key 的额度设置 |
| 请求超时 | 视频、长文这类任务本身耗时较长 | 提高客户端超时时间,或改用异步任务方式提交 |
| 返回内容被截断 | 达到了 max_tokens 限制 | 调大 max_tokens,或让模型分段输出 |
MIGRATION
把已有 OpenAI 项目迁移过来
ONLY 2 LINES
只改两行
绝大多数情况下,只需要把接口地址和 Key 换掉,其余逻辑完全不用动。
# 迁移前
base_url = "https://api.openai.com/v1"
api_key = "sk-..."
# 迁移后
base_url = "https://<HrioAI 接口地址>/v1"
api_key = "<HrioAI 控制台创建的 Key>"
使用 LangChain、Cherry Studio、各类 IDE 插件或桌面客户端时,原理相同:在设置里找到「自定义 API 地址 / Base URL」和「API Key」两个字段填进去,再选择模型即可。