API文档

傻瓜式教程 · 一看就懂 · 完全兼容OpenAI API格式

快速导航

1. 快速开始

只需3步，即可开始使用金牛AI平台的API服务。

1
登录注册

点击页面右上角的「金牛ID登录」按钮，使用您的金牛ID（JNQJ ID）登录平台。如果您还没有金牛ID，系统会引导您完成注册。新用户注册即赠送1000元余额，可直接用于API调用。

2
创建API Key

登录后进入「API密钥」页面，点击「创建密钥」按钮：

  • 填写应用名称（如：我的AI应用）
  • 填写备注信息（可选）
  • 点击保存后，系统会生成一个以 JNQJ-API- 开头的API Key
  • 请务必妥善保管您的API Key，它只显示一次！
3
调用API

使用您创建的API Key，向本站API地址发送请求。最简单的方式是使用curl命令：

curl http://192.168.3.166:10025/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "local-model",
    "messages": [
      {"role": "system", "content": "你是人工智能助手"},
      {"role": "user", "content": "你好"}
    ]
  }'

将 JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 替换为您实际的API Key即可。

2. API地址说明

API基础地址 http://192.168.3.166:10025
API前缀 /api/v3
完整端点 http://192.168.3.166:10025/api/v3/chat/completions
请求方式 POST
局域网访问 本API地址支持局域网内所有人访问（192.168.x.x 网段）

重要提示：本平台是纯数据中转站，不提供任何算力服务。所有API请求将通过本平台转发至您在「渠道管理」中配置的上游算力API。请在使用前先完成渠道配置。

3. 认证方式

本平台使用 Bearer Token 认证方式。在每次API请求的HTTP头中携带您的API Key即可。

认证Header格式

Authorization: Bearer JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

支持的认证方式

方式 Header名称 格式 说明
推荐 Authorization Bearer JNQJ-API-xxx 标准Bearer Token方式，与OpenAI兼容
备选 api-key JNQJ-API-xxx 直接在api-key头中传值
备选 URL参数 ?api_key=JNQJ-API-xxx 通过URL查询参数传递（不推荐）

4. 请求格式

本平台完全兼容 OpenAI Chat Completions API 格式。请求体为JSON格式，包含以下参数：

请求示例

{
    "model": "local-model",
    "messages": [
        {"role": "system", "content": "你是人工智能助手"},
        {"role": "user", "content": "你好"}
    ],
    "stream": false,
    "temperature": 0.7,
    "max_tokens": 4096
}

参数说明

参数名 类型 必填 默认值 说明
model string 是 - 模型名称，需与渠道管理中配置的「平台模型名」一致
messages array 是 - 消息列表，包含对话历史
role (string) - 消息角色：system（系统提示）、user（用户消息）、assistant（助手回复）
content (string) - 消息内容
stream boolean 否 false 是否使用流式输出（SSE），开启后逐字返回内容
temperature number 否 1 温度参数（0~2），值越高输出越随机，值越低输出越确定
max_tokens integer 否 - 最大生成Token数，限制回复长度
top_p number 否 1 核采样参数（0~1），与temperature二选一使用
n integer 否 1 生成回复的数量
stop string/array 否 - 停止词，遇到这些词时停止生成
frequency_penalty number 否 0 频率惩罚（-2~2），正值减少重复词
presence_penalty number 否 0 存在惩罚（-2~2），正值鼓励新话题
user string 否 - 用户标识，用于区分不同终端用户

5. 响应格式

成功响应（非流式）

当 stream 为 false 时，返回完整的JSON响应：

{
    "id": "chatcmpl-abc123def456",
    "object": "chat.completion",
    "created": 1700000000,
    "model": "local-model",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "你好！我是人工智能助手，有什么可以帮助您的吗？"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 10,
        "completion_tokens": 20,
        "total_tokens": 30
    }
}

错误响应

当请求出错时（如认证失败、参数错误等），返回错误信息：

{
    "error": {
        "message": "Invalid API key. Please check your Authorization header.",
        "type": "authentication_error",
        "code": 401
    }
}

流式响应（SSE）

当 stream 为 true 时，以Server-Sent Events格式逐块返回：

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1700000000,"model":"local-model","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1700000000,"model":"local-model","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1700000000,"model":"local-model","choices":[{"index":0,"delta":{"content":"！"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1700000000,"model":"local-model","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

响应字段说明

字段 类型 说明
idstring请求唯一标识
objectstring对象类型，固定为 chat.completion
createdinteger创建时间戳
modelstring使用的模型名称
choicesarray回复列表
choices[].message.role - 回复角色（assistant）
choices[].message.content - 回复内容
choices[].finish_reason - 结束原因（stop/length/content_filter）
usageobjectToken使用统计
usage.prompt_tokens - 输入Token数
usage.completion_tokens - 输出Token数
usage.total_tokens - 总Token数

6. 代码示例

以下是各主流编程语言的调用示例，所有示例均使用相同的API地址和认证方式。

使用PHP的cURL扩展发送请求

<?php
$apiKey = 'JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$url = 'http://192.168.3.166:10025/api/v3/chat/completions';

$data = [
    'model' => 'local-model',
    'messages' => [
        ['role' => 'system', 'content' => '你是人工智能助手'],
        ['role' => 'user', 'content' => '你好']
    ],
    'stream' => false
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;

使用Python的requests库发送请求，需安装 pip install requests

import requests

api_key = "JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
url = "http://192.168.3.166:10025/api/v3/chat/completions"

data = {
    "model": "local-model",
    "messages": [
        {"role": "system", "content": "你是人工智能助手"},
        {"role": "user", "content": "你好"}
    ],
    "stream": False
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {api_key}"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

使用Go标准库 net/http 发送请求

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    apiKey := "JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    url := "http://192.168.3.166:10025/api/v3/chat/completions"

    data := map[string]interface{}{
        "model": "local-model",
        "messages": []map[string]string{
            {"role": "system", "content": "你是人工智能助手"},
            {"role": "user", "content": "你好"},
        },
        "stream": false,
    }

    jsonData, _ := json.Marshal(data)
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

使用 reqwest + tokio 异步发送请求，需在 Cargo.toml 中添加依赖

use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = "JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
    let url = "http://192.168.3.166:10025/api/v3/chat/completions";

    let body = serde_json::json!({
        "model": "local-model",
        "messages": [
            {"role": "system", "content": "你是人工智能助手"},
            {"role": "user", "content": "你好"}
        ],
        "stream": false
    });

    let client = reqwest::Client::new();
    let resp = client
        .post(url)
        .header("Authorization", format!("Bearer {}", api_key))
        .header("Content-Type", "application/json")
        .json(&body)
        .send()
        .await?
        .text()
        .await?;

    println!("{}", resp);
    Ok(())
}

使用curl命令行工具直接测试API

curl http://192.168.3.166:10025/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "local-model",
    "messages": [
      {"role": "system", "content": "你是人工智能助手"},
      {"role": "user", "content": "你好"}
    ]
  }'

使用JavaScript的fetch API发送请求（浏览器或Node.js环境）

const apiKey = "JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const url = "http://192.168.3.166:10025/api/v3/chat/completions";

const data = {
    model: "local-model",
    messages: [
        { role: "system", content: "你是人工智能助手" },
        { role: "user", content: "你好" }
    ],
    stream: false
};

fetch(url, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

7. 本地算力对接教程

本节详细说明如何对接运行在 127.0.0.1:10026 端口的本地算力API。通过以下4步即可完成对接。

1
在渠道管理中添加渠道

登录平台后，进入「渠道管理」页面，点击「创建渠道」按钮，填写以下信息：

配置项填写内容说明
渠道名称本地算力自定义名称，便于识别
渠道类型custom选择自定义类型
基础地址http://127.0.0.1:10026/v1本地算力服务的API地址
API密钥（您的本地密钥）本地算力服务的API Key，如无认证可留空
认证方式Bearer Token标准Bearer认证
2
配置模型映射

在创建渠道时，同时配置模型映射关系。模型映射用于将平台模型名映射到上游算力的实际模型名：

配置项填写内容说明
平台模型名local-model调用API时使用的模型名
上游模型名local-model本地算力服务实际的模型名
输入价格0本地算力可设为0
输出价格0本地算力可设为0
最大Token数4096根据本地模型能力设置

提示：平台模型名是您在调用API时 model 参数填写的值，上游模型名是本地算力服务识别的模型名。两者可以不同。

3
获取API Key

进入「API密钥」页面，创建一个新的API Key。系统会生成以 JNQJ-API- 开头的密钥，请妥善保存。这个Key是您调用金牛AI平台API的凭证，平台会通过此Key识别您的身份并转发请求到您配置的本地算力。

4
调用API

使用您的API Key，向金牛AI平台发送请求，model 参数填写步骤2中配置的「平台模型名」：

curl http://192.168.3.166:10025/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "local-model",
    "messages": [
      {"role": "system", "content": "你是人工智能助手"},
      {"role": "user", "content": "你好"}
    ]
  }'

请求流程：您的应用 → 金牛AI平台（中转） → 127.0.0.1:10026（本地算力） → 返回结果

8. 真实案例

以下是3个真实对接案例，展示如何对接不同类型的算力服务。

案例1：对接本地算力 127.0.0.1:10026

场景：您在本地机器上部署了AI模型，运行在10026端口，希望通过金牛AI平台统一管理和计费。

渠道配置
配置项值
渠道名称本地算力
渠道类型custom
基础地址http://127.0.0.1:10026/v1
认证方式Bearer Token
平台模型名local-model
上游模型名local-model
API调用示例
curl http://192.168.3.166:10025/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "local-model",
    "messages": [
      {"role": "user", "content": "用Python写一个快速排序"}
    ],
    "stream": true
  }'

案例2：对接豆包模型

场景：您有火山引擎豆包大模型的API权限，希望通过金牛AI平台统一调用和管理。

渠道配置
配置项值
渠道名称豆包大模型
渠道类型custom
基础地址https://ark.cn-beijing.volces.com/api/v3
API密钥（您的火山引擎API Key）
认证方式Bearer Token
平台模型名doubao-pro-32k
上游模型名ep-xxxxxxxxxxxx-xxxxx（豆包端点ID）
API调用示例
curl http://192.168.3.166:10025/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "doubao-pro-32k",
    "messages": [
      {"role": "system", "content": "你是一个专业的翻译助手"},
      {"role": "user", "content": "请将以下英文翻译成中文：Hello World"}
    ],
    "temperature": 0.3
  }'

豆包模型的上游模型名是火山引擎的端点ID（Endpoint ID），格式为 ep-xxxxxxxx，可在火山引擎控制台获取。

案例3：对接小米MiMo模型

场景：您有小米MiMo大模型的API权限，希望通过金牛AI平台进行调用和计费管理。

渠道配置
配置项值
渠道名称小米MiMo
渠道类型custom
基础地址https://api.mimo.xiaomi.com/v1
API密钥（您的小米API Key）
认证方式Bearer Token
平台模型名mimo-7b
上游模型名MiMo-7B-RL
API调用示例
curl http://192.168.3.166:10025/api/v3/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JNQJ-API-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "mimo-7b",
    "messages": [
      {"role": "user", "content": "解释一下量子计算的基本原理"}
    ],
    "max_tokens": 2048
  }'

小米MiMo模型支持多种规格，请根据实际需求选择对应的模型名称。

9. 计费说明

本平台采用透明、简单的计费方式，按实际使用量收费。

1元/GB
流量计费

按实际传输的数据流量计费，包括请求和响应的数据大小

0.01元/MB
存储计费

按实际占用的存储空间计费，用于保存请求日志等数据

1000元
新用户赠送

注册即送1000元余额，赠送金额优先扣除

计费规则说明
  • 流量费用：每次API调用产生的数据传输量，按 1元/GB 计算（即 0.001元/MB）
  • 存储费用：平台保存的请求日志等数据，按 0.01元/MB 计算
  • 赠送余额：新用户注册赠送1000元，消费时优先扣除赠送余额
  • 充值余额：赠送余额用完后，从充值余额中扣除
  • 余额不足：余额不足时API请求将返回403错误，请及时充值
  • 实时计费：每次请求完成后立即扣费，可在「用量统计」页面查看明细

10. 中转流程图

本平台仅负责数据转发，不参与任何算力运算。

用户请求
您的应用发送请求
金牛AI平台
中转转发 · 计费
上游算力API
本地/云端算力
返回结果
实时响应给用户

金牛AI平台在转发过程中仅做数据中转和计费记录，不会存储或修改您的对话内容

11. 常见问题（FAQ）

登录平台后，进入「API密钥」页面，点击「创建密钥」按钮。填写应用名称和备注后保存，系统会生成以 JNQJ-API- 开头的API Key。请注意，API Key只在创建时显示一次，请务必复制保存。如果不慎丢失，可以删除旧Key后重新创建。

本平台是纯数据中转站，不自带任何模型。您可以通过「渠道管理」对接任意支持OpenAI兼容API格式的算力服务，包括但不限于：本地部署的模型（如vLLM、Ollama）、火山引擎豆包、小米MiMo、OpenAI GPT等。只要上游服务兼容OpenAI API格式即可对接。

本平台按流量计费（1元/GB）和按存储计费（0.01元/MB）。每次API调用产生的数据传输量按流量费计算，保存的请求日志按存储费计算。新用户注册赠送1000元余额，消费时优先扣除赠送余额，再扣除充值余额。所有费用明细可在「用量统计」页面查看。

非流式（stream=false）：等待模型生成完毕后，一次性返回完整的JSON响应。适合后台任务或不需要实时展示的场景。

流式（stream=true）：以Server-Sent Events（SSE）格式逐块返回内容，用户可以实时看到生成过程。适合聊天对话、实时交互等场景。使用流式时需注意客户端需要正确处理SSE格式的数据流。

可以！本平台完全兼容OpenAI API格式。您只需将OpenAI SDK中的 base_url 替换为本平台API地址 http://192.168.3.166:10025/api/v3，api_key 替换为您的 JNQJ-API-xxx 即可，代码无需做任何其他修改。

401错误表示认证失败。请检查以下几点：
1. 确认API Key格式正确，以 JNQJ-API- 开头
2. 确认Authorization头格式为 Bearer JNQJ-API-xxx
3. 确认API Key未被删除或禁用
4. 确认账户状态正常（未被冻结）

403错误表示余额不足。请进入「计费充值」页面进行充值。充值后余额立即到账，API服务自动恢复。您也可以在「用量统计」页面查看消费明细，了解余额使用情况。

请参考本文档第7节「本地算力对接教程」。简单来说：在「渠道管理」中创建渠道，基础地址填写本地算力服务地址（如 http://127.0.0.1:10026/v1），配置模型映射，然后使用平台API Key调用即可。平台会自动将请求转发到您的本地算力服务。

平台对每个API Key设有默认的频率限制（60次/分钟）。如果需要更高的频率限制，可以在「API密钥」页面修改Key的速率限制参数。如果请求频率超过限制，平台会返回429错误，请适当降低请求频率或使用排队机制。

平台会记录请求日志用于计费和统计，但会对消息内容进行脱敏处理（仅保留前50个字符），不会完整存储您的对话内容。平台在转发过程中仅做数据中转，不会修改您的请求或响应数据。