API 文档

欢迎使用 KG API 中转站！这是一个功能完整的 API 网关，提供 OpenAI 兼容的接口、Claude 消息 API、图片生成等多种服务。本文档将帮助您快速上手使用我们的服务。

基础信息：
Base URL: https://www.nbapi.com.cn
API Version: v1
支持流式响应和 WebSocket 连接

快速开始

在 3 分钟内完成您的第一个 API 调用。

1. 获取 API Key

访问 Token 页面获取您的 API Key（或使用演示 Key）。

2. 发送您的第一个请求

使用下面的代码进行测试：

curl https://www.nbapi.com.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://www.nbapi.com.cn"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

const response = await fetch('https://www.nbapi.com.cn/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [{role: 'user', content: 'Hello'}]
  })
});
const data = await response.json();
console.log(data.choices[0].message.content);

获取 API Key

使用 API Key 来认证您的请求。所有 API 请求都需要有效的 API Key。

演示 Key： 访问 /token 页面获取您的专属 API Key，或直接使用提供的演示 Key 进行测试。

认证方法

在请求头中包含您的 API Key：

Authorization: Bearer YOUR_API_KEY

或在查询参数中传递（某些端点支持）：

https://www.nbapi.com.cn/v1/chat/completions?api_key=YOUR_API_KEY

Chat Completions

使用 Chat Completions API 与 AI 模型进行对话。支持多轮对话、流式响应和函数调用。

端点

POST /v1/chat/completions

请求体

参数	类型	必需	描述
`model`	string	是	模型 ID，如 gpt-4o, gpt-4-turbo, gpt-3.5-turbo
`messages`	array	是	消息列表，包含 role 和 content
`temperature`	number	否	采样温度（0-2），默认 1
`max_tokens`	number	否	最大令牌数
`stream`	boolean	否	是否使用流式响应

示例

curl -X POST https://www.nbapi.com.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "What is AI?"}], "temperature": 0.7}'

import openai

client = openai.OpenAI(api_key="YOUR_API_KEY", base_url="https://www.nbapi.com.cn")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "What is AI?"}
    ],
    temperature=0.7
)

print(response.choices[0].message.content)

const response = await fetch('https://www.nbapi.com.cn/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [{role: 'user', content: 'What is AI?'}],
    temperature: 0.7
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

Responses API

Responses API 提供了一个简化的接口用于快速生成响应。适合于需要快速推理的场景。

端点

POST /v1/responses

请求体

参数	类型	描述
`model`	string	模型 ID
`input`	string	输入文本
`max_tokens`	number	最大响应令牌数

示例

curl -X POST https://www.nbapi.com.cn/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model": "gpt-4o", "input": "Explain quantum computing", "max_tokens": 500}'

Claude Messages API

直接使用 Claude Messages API 格式调用 Claude 模型。这是 Anthropic 原生的 API 格式。

端点

POST /v1/messages

认证

Claude Messages API 使用专门的 x-api-key 头部：

x-api-key: YOUR_API_KEY

请求体

参数	类型	必需	描述
`model`	string	是	Claude 模型 ID，如 claude-3-5-sonnet, claude-3-opus
`messages`	array	是	消息列表
`max_tokens`	number	是	最大响应令牌数
`system`	string	否	系统提示词

示例

curl https://www.nbapi.com.cn/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"model": "claude-3-5-sonnet", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello Claude"}]}'

import anthropic

client = anthropic.Anthropic(api_key="YOUR_API_KEY")

response = client.messages.create(
    model="claude-3-5-sonnet",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello Claude"}
    ]
)

print(response.content[0].text)

const response = await fetch('https://www.nbapi.com.cn/v1/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'claude-3-5-sonnet',
    max_tokens: 1024,
    messages: [{role: 'user', content: 'Hello Claude'}]
  })
});

const data = await response.json();
console.log(data.content[0].text);

Embeddings

使用 Embeddings API 将文本转换为向量表示。适用于相似度搜索、聚类等任务。

端点

POST /v1/embeddings

请求体

参数	类型	必需	描述
`model`	string	是	嵌入模型 ID，如 text-embedding-3-small
`input`	string \| array	是	要嵌入的文本或文本数组

示例

curl -X POST https://www.nbapi.com.cn/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model": "text-embedding-3-small", "input": ["Hello world", "How are you"]}'

响应示例

                    {
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.0234, 0.0512, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {"prompt_tokens": 4, "total_tokens": 4}
}
                

图片生成

使用 DALL-E API 生成、编辑和变化图像。支持不同的分辨率和风格。

端点

POST /v1/images/generations

请求体

参数	类型	必需	描述
`prompt`	string	是	描述要生成的图像的文本提示
`model`	string	是	模型 ID，如 dall-e-3
`size`	string	否	1024x1024, 1792x1024, 或 1024x1792，默认 1024x1024
`quality`	string	否	standard 或 hd，默认 standard
`n`	number	否	生成图像数量（1-10），默认 1

示例

curl -X POST https://www.nbapi.com.cn/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model": "dall-e-3", "prompt": "A sunset over mountains", "size": "1024x1024"}'

流式响应

使用 Server-Sent Events (SSE) 实现流式响应。适合于长时间运行的操作或实时数据推送。

启用流式响应

在请求体中设置 stream: true：

{ "model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}], "stream": true }

JavaScript 中解析流式响应

async function streamChat(prompt) {
  const response = await fetch('https://www.nbapi.com.cn/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
      model: 'gpt-4o',
      messages: [{role: 'user', content: prompt}],
      stream: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const {done, value} = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const json = line.substring(6);
        const data = JSON.parse(json);
        // 处理每个块
        console.log(data.choices[0].delta);
      }
    }
  }
}

Python 中解析流式响应

import openai

client = openai.OpenAI(api_key="YOUR_API_KEY", base_url="https://www.nbapi.com.cn")

with client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
) as stream:
    for text in stream.text_stream():
        print(text, end="", flush=True)

错误处理

了解 API 返回的错误代码和如何处理它们。

常见错误代码

状态码	错误代码	描述	处理方式
`401`	invalid_api_key	API Key 无效或已过期	检查 API Key 是否正确，重新获取新 Key
`402`	insufficient_quota	账户余额不足或配额已用尽	充值或购买更多配额
`429`	rate_limit_exceeded	请求频率超过限制	等待后重试，实现指数退避
`500`	internal_server_error	服务器内部错误	稍后重试，联系技术支持
`503`	service_unavailable	服务暂时不可用	等待服务恢复后重试

错误响应格式：
所有错误响应都包含 error 对象，包括 code、message 和 type。

错误响应示例

                    {
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "type": "rate_limit_error"
  }
}
                

实现重试逻辑（Python）

import time
import random

def call_api_with_retry(client, **kwargs):
    max_retries = 3
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except Exception as e:
            if 'rate_limit' in str(e):
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                print(f"Rate limited, waiting {wait_time}s")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("Max retries exceeded")

最佳实践

1. API Key 安全

• 不要在客户端代码中暴露 API Key
• 使用环境变量存储敏感信息
• 定期轮换 API Key
• 如果 Key 泄露，立即在后台撤销

2. 错误处理

• 实现指数退避的重试机制
• 处理超时和连接错误
• 记录错误详情用于调试
• 为用户提供有意义的错误消息

3. 性能优化

• 使用流式响应处理大型响应
• 批处理多个请求
• 缓存频繁的查询结果
• 监控 API 使用情况和成本

4. 提示工程

• 编写清晰具体的提示
• 使用角色扮演改进输出
• 提供示例以指导 AI 行为
• 实验不同的温度和参数

获取帮助

如果您遇到问题或有疑问，请通过以下方式联系我们：

站内支持

前往账户中心查看最新接入信息

在线咨询

进入站内页面继续咨询或测试接口