接入文档 · DOCS

API 接入文档与资料库

从网关地址、鉴权方式到各语言调用示例与错误码,一页看懂怎么把模型接进你自己的系统。

1快速开始

四步把模型接进你自己的系统。全程只需要一个 API Key 和一个 base_url,任何支持 OpenAI 协议的 SDK 或框架都能直接用。

① 注册并登录

在 API 控制台 登录 51-ai.cn 账号(支持密码或邮箱验证码)。

② 创建 API Key

登录后点击「创建新密钥」。密钥格式为 sk-51-…,仅在创建时展示一次,请立即保存。

③ 配置 base_url

把 SDK 的 base_url 指向我们的网关,api_key 填刚创建的密钥。

④ 发出第一个请求

调用 /v1/chat/completions,model 填模型标准调用名称(见第 6 节)。

最小可用示例

curl https://api.51-ai.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-51-你的密钥" \
  -d '{
    "model": "deepseek-v4.1-flash-1017",
    "messages": [
      {"role": "user", "content": "你好,介绍一下你自己"}
    ]
  }'

2网关与接入点

统一入口只有一个:https://api.51-ai.cn/v1。所有模型都从这一个地址进,model 参数决定用哪个模型——换模型不用换地址。如你需要其它接入点(专线 / 海外节点),请联系商务单独开通。

统一入口https://api.51-ai.cn/v1

完整请求地址

能力路径方法
对话补全/v1/chat/completionsPOST
模型列表(含开通状态)/v1/modelsGET

即对话补全地址为 https://api.51-ai.cn/v1/chat/completions,模型列表为 https://api.51-ai.cn/v1/models。SDK 里填 base_url="https://api.51-ai.cn/v1" 即可。

模型不是「列出来就能调」——先看开通状态

GET /v1/models 会返回平台全部模型,其中 active: true 的才是当前已开通、可直接调用的(返回值里的 gateway.active_count 就是数量)。active: false 表示模型在售但尚未在你所用的网关开通,直接调用会返回 403 model_not_activated——请在控制台申请开通后再用。

3鉴权

所有请求都需要在 HTTP 头里带上 Bearer Token。密钥与账号绑定,可在控制台随时创建或撤销。

Authorization: Bearer sk-51-你的密钥
Content-Type: application/json

安全建议

密钥等同于账号权限,请只保存在服务端环境变量中,不要写进前端代码或提交到代码仓库。发现泄露请立刻到控制台撤销并重建。

4OpenAI 兼容接口

POST /v1/chat/completions 完全兼容 OpenAI 协议,换模型只需要改 model 参数。

请求参数

参数类型必填说明
modelstring是模型标准调用名称,见 模型广场
messagesarray是system / user / assistant 角色消息数组
max_tokensinteger否最大输出长度,通用上限 4096
temperaturenumber否0–2,越大越随机
streamboolean否为 true 时以 SSE 流式返回
top_p / stop—否与 OpenAI 语义一致

响应结构

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1757660000,
  "model": "deepseek-v4.1-flash-1017",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好!我是…" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 88, "total_tokens": 100 }
}

流式模式下返回 text/event-stream,每个事件形如 data: {"choices":[{"delta":{"content":"…"}}]},以 data: [DONE] 结束。

5代码示例

同一份代码把 base_url 换成国内或海外网关即可,其余不用改。

cURL

curl https://api.51-ai.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-51-你的密钥" \
  -d '{
    "model": "deepseek-v4.1-flash-1017",
    "messages": [
      {"role": "system", "content": "你是一个乐于助人的助手"},
      {"role": "user", "content": "你好,介绍一下你自己"}
    ]
  }'

Python(openai SDK)

from openai import OpenAI

client = OpenAI(
    api_key="sk-51-你的密钥",
    base_url="https://api.51-ai.cn/v1"
)

resp = client.chat.completions.create(
    model="deepseek-v4.1-flash-1017",
    messages=[{"role": "user", "content": "你好,介绍一下你自己"}],
)
print(resp.choices[0].message.content)

# 流式输出
stream = client.chat.completions.create(
    model="deepseek-v4.1-flash-1017",
    messages=[{"role": "user", "content": "写一首关于春天的诗"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-51-你的密钥",
  baseURL: "https://api.51-ai.cn/v1",
});

const resp = await client.chat.completions.create({
  model: "deepseek-v4.1-flash-1017",
  messages: [{ role: "user", content: "你好,介绍一下你自己" }],
});
console.log(resp.choices[0].message.content);

原生 fetch 流式(浏览器 / 边缘运行时)

const res = await fetch("https://api.51-ai.cn/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-51-你的密钥",
  },
  body: JSON.stringify({
    model: "Claude-Opus-4.8",
    stream: true,
    messages: [{ role: "user", content: "用三句话介绍你自己" }],
  }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

6模型与调用名

model 参数填模型名(如 DeepSeek-V3.2、Claude-Sonnet-4.5)。海外模型另外支持平台代称(如 C-S-4.5),两种写法都能调通。完整清单与单价见 模型广场与报价。

厂商节选模型调用名类型
DeepSeekDeepSeek-R1-0528 · DeepSeek-V3.2 · DeepSeek-V4.1-Flash文本 / 视觉
智谱 GLMGLM-5.3 · GLM-5.2 · GLM-4.6文本 / 多模态
通义千问Qwen3-Max · Qwen3-VL-235B-A22B-Instruct文本 / 多模态
Anthropic ClaudeClaude-Sonnet-4.5 · Claude-Opus-4.5 · Claude-Haiku-4.5多模态
OpenAI GPTGPT-5.2 · GPT-5.5 · GPT-6-Sol多模态
Google GeminiGemini-3-Pro-Preview · Gemini-3.8-Flash多模态
xAI GrokGrok-4 · Grok-4.6文本

海外模型需要先开通

平台对海外模型标注「需单独申请开通权限」。未开通直接调用会返回 403。请在 API 控制台 查看当前可调用清单,需要新增模型请 联系商务 申请。

静态获取可用模型

调用 GET /v1/models 可以随时拉取当前账号可用的模型列表,避免把模型名写死在代码里。

7计费与额度

项目规则
计费方式按 token 用量计费(prompt + completion),流式按最终 usage 计
计价单位每百万 Token(1M tokens)。图像模型按每张图片计价
输入 / 输出分别计价,输出单价通常高于输入;部分模型按上下文长度分档(如 GPT 系列的 ≤272K / ≥272K)
缓存命中输入命中缓存的输入按「缓存命中输入」单价计,低于常规输入单价;未命中的按常规输入单价计
价格口径页面与接口只提供原价(缓存命中输入 / 常规输入 / 输出)。合同折扣与批量价由商务确认
余额与工作台对话共用账户余额,实时扣减
余额不足返回 HTTP 402 insufficient_quota,充值后自动恢复

8错误码

HTTP含义处理建议
400请求参数错误(缺少 messages、model 不存在等)检查请求体格式与 model 名称
401密钥无效、已撤销或未带 Authorization 头到控制台重新生成密钥
402余额不足充值后重试,或联系商务开通企业额度
403模型未开通(错误码 model_not_activated)改用在 /v1/models 里 active=true 的模型,或到控制台申请开通。重试无效,不要放进重试逻辑
404路径不存在确认 base_url 与接口路径是否正确
429触发限流降低并发或退避重试
500 / 502上游模型服务异常或超时稍后重试;持续失败请联系客服

9限流与最佳实践

并发与限流

默认按账号设置并发与 RPM 上限。需要更高并发请在商务侧申请提额,说明模型、峰值 QPS 与业务场景。

超时与重试

建议客户端超时设为 60s 以上;对 429 / 5xx 采用指数退避重试(最多 2–3 次),不要无脑重试。

长上下文

超过 272K 上下文的请求在 GPT 系列上会命中更高档位的单价,建议先裁剪无关上下文再接缓存。

用好缓存

固定前缀(系统提示词、知识库片段)放在 messages 前部,可命中上下文缓存,明显降低输入成本。

10常见问题

已经用 OpenAI SDK 了,要改多少代码?

只改两个地方:base_url 指向我们的网关,api_key 换成 sk-51-…。其余代码不用动。

同一个 Key 能调用多个厂商的模型吗?

可以。一个 Key 通用,通过 model 参数切换模型即可,不需要为每个厂商单独申请密钥。

只有国内一个入口吗?海外业务怎么办?

对外统一入口只有 https://api.51-ai.cn/v1,国内外模型都从这一个地址进,靠 model 参数选。需要专线或海外节点(更低延迟 / 合规要求)请联系商务单独开通,开通后会给你专属 base_url,代码只需改这一处。

密钥找不到了怎么办?

密钥只在创建时展示一次。如果没保存,到控制台撤销旧密钥后重新创建一个即可。

如何获取企业批量价格?

到 模型广场与报价 查看当前折扣,或 联系商务 获取年度框架与批量价格。