文档

对接文档

兼容 OpenAI 接口格式。已有代码只需替换 Base URL 和 API 密钥，几分钟即可接入。

概述

hinnflowAI 是一个 AI 模型网关：一把 API 密钥即可调用多家厂商的模型，统一计费、统一用量统计。接口遵循 OpenAI API 格式，任何兼容 OpenAI 的 SDK、框架和客户端都可以直接使用。

项目值
Base URLhttps://api.hinnflow.com/v1
鉴权方式Authorization: Bearer <API 密钥>
数据格式请求与响应均为 JSON，Content-Type: application/json
流式输出Server-Sent Events（stream: true）

快速开始

  1. 注册并登录账号。
  2. 进入控制台 → API 密钥，新建一个密钥并复制保存（以 sk- 开头）。
  3. 在钱包充值，或使用兑换码。
  4. 在你的代码里把 Base URL 设为 https://api.hinnflow.com/v1，API Key 设为刚才的密钥，发起第一次调用：
curl https://api.hinnflow.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "用一句话介绍你自己。"}
    ]
  }'
示例里的 deepseek-v4-flash 可以换成模型广场中的任意模型名。

鉴权

每个请求都要在请求头里带上 API 密钥：

HTTP
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
  • 密钥等同于你的账户余额，只在服务端使用，不要写进前端代码、App 安装包或公开仓库。
  • 可以为不同项目创建不同的密钥，并分别设置额度上限、过期时间、可用模型和 IP 白名单。
  • 密钥泄露时，在控制台禁用或删除即可立即失效。

对话补全

POST/v1/chat/completions

根据对话上下文生成回复，是最常用的接口。常用参数：

参数类型必填说明
modelstring是模型名称，见模型广场
messagesarray是对话消息列表，每条包含 role（system / user / assistant）和 content
streamboolean否是否流式返回，默认 false
temperaturenumber否采样温度，0–2，越高越随机
max_tokensinteger否本次回复最多生成的 token 数
top_pnumber否核采样阈值，一般与 temperature 二选一调整
toolsarray否函数调用（Function Calling）的工具定义，需模型支持

其余参数与 OpenAI 官方接口一致，网关会原样转发给上游模型。响应示例：

JSON
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1792560000,
  "model": "deepseek-v4-flash",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 86,
    "total_tokens": 110
  }
}
usage 里的 token 数就是本次计费的依据，在控制台 → 使用日志可以查到每次请求的明细。

流式输出

请求里加上 "stream": true，响应会以 SSE 事件流逐段返回，适合聊天界面边生成边显示。以 data: [DONE] 结束。

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "写一首关于海的短诗。"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content if chunk.choices else None
    if delta:
        print(delta, end="", flush=True)

原始事件流的格式：

SSE
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"浪花"}}]}

data: [DONE]
如果你在 Nginx 等反向代理后面转发流式响应，记得关闭缓冲（proxy_buffering off;），否则内容会攒到最后一次性返回。

模型列表

GET/v1/models

返回当前密钥可调用的全部模型。如果密钥设置了模型限制，这里只会列出被允许的模型。价格与可用性请看模型广场。

curl https://api.hinnflow.com/v1/models \
  -H "Authorization: Bearer $API_KEY"

其他接口

网关基于 new-api，除对话补全外还兼容以下 OpenAI 格式接口。某个模型具体支持哪些端点，以模型广场详情里标注的为准。

接口方法与路径用途
ResponsesPOST /v1/responsesOpenAI 新版响应接口
EmbeddingsPOST /v1/embeddings文本向量化
ImagesPOST /v1/images/generations图像生成
AudioPOST /v1/audio/transcriptions、/v1/audio/speech语音识别与语音合成

更完整的参数说明可参考 new-api 的 API 参考文档。

错误处理

出错时返回非 2xx 状态码，响应体格式与 OpenAI 一致：

JSON
{
  "error": {
    "message": "Invalid token (request id: 2026102110...)",
    "type": "new_api_error",
    "code": ""
  }
}
状态码常见原因处理建议
400请求参数有误，或模型名称不存在检查请求体与 model 字段
401API 密钥无效、已禁用或已过期在控制台确认密钥状态
403余额或密钥额度不足、模型不在允许范围、IP 不在白名单充值或调整密钥设置
429请求过于频繁，或上游限流降低并发，按指数退避重试
500 / 502 / 503上游服务异常或暂时不可用稍后重试；持续出现请联系我们
错误信息里的 request id 能帮我们快速定位问题，反馈时请一并提供。

计费说明

  • 大多数模型按 token 计费：输入与输出分别计价，单价见模型广场，以每百万 token 的美元价格标注。
  • 部分模型按次计费，或按时段、上下文长度分档计价（模型广场里标为"动态计费"）。
  • 上游报错导致请求失败时不扣费，预扣的额度会退回。
  • 余额与每次请求的消耗可在控制台查看。

常见问题

问题解答
Base URL 要不要带 /v1？OpenAI 官方 SDK 需要带：https://api.hinnflow.com/v1。有些客户端只需填 https://api.hinnflow.com，会自动补上 /v1，以客户端自己的说明为准。
能用在哪些工具里？任何支持"自定义 OpenAI 接口地址"的工具都可以，例如 Cherry Studio、LobeChat、Dify、LangChain、Cursor 等。
报 401 怎么办？确认请求头是 Authorization: Bearer sk-...，且密钥在控制台中处于"已启用"状态。
流式输出不生效？确认传了 "stream": true；经过反向代理时需要关闭代理缓冲。