小蓝助手开发者文档

API 与模型使用文档

按统一 Token 接入的实际流程整理，从创建 Key、选择模型到调用 API 和排查错误，适合开发者、办公工具和业务系统接入。

管理 API Key 查看模型广场 进入控制台

先看这里

小蓝助手的模型调用由统一 Token 网关承接，底层算力来自合作的 TokenHub 服务。你只需要在小蓝助手控制台管理自己的账号、Key、余额和用量；不要使用上游平台的账号或密钥。

一套 Key

使用小蓝助手控制台生成的 API Key 调用当前账号有权限的模型。网站登录密码不能填入 API Key 字段。

一个入口

OpenAI 兼容客户端统一使用 https://api.bluedoai.com/v1，模型名称以模型广场和接口返回为准。

实时配置

模型可用状态、倍率、余额和权限会随平台配置变化，生产接入前请在模型广场和控制台复核。

快速入门

第一次接入按下面四步完成，先用最小请求验证 Key 和模型名。

1. 注册或登录

进入小蓝助手控制台完成账号登录。

进入

2. 创建 API Key

打开 Key 页面创建密钥，只在本地密码管理器或服务端密钥存储中保存。

进入

3. 选择模型

在模型广场确认模型名称、能力和当前计费信息。

进入

4. 发起测试请求

先调用模型列表或聊天接口，确认返回状态、模型名和用量记录，再接入正式业务。

接口配置

以下是小蓝助手网关的公开接入格式。未登录请求返回 401 只表示需要有效 Key，不代表接口路径不存在。

API Base URL

https://api.bluedoai.com/v1

鉴权方式

Authorization: Bearer <你的 API Key>

模型列表

GET /models，查看当前 Key 可用的模型列表。

聊天对话

POST /chat/completions，适用于 OpenAI 兼容的聊天客户端和业务代码。

Responses

POST /responses，使用前以当前模型和客户端支持情况为准。

图片、向量和视频

平台可能按模型和账户权限开放图片生成、嵌入或视频任务；请以模型广场和接口返回为准，不要把未授权状态写成已开通能力。

最小请求示例

运行示例前，将小蓝助手控制台创建的 Key 保存为 XIAOLAN_API_KEY 环境变量。示例中的密钥只使用占位符，不要把真实 Key 写进网页、代码仓库、截图或聊天记录。

查询模型

先确认网关和 Key 可用，再从返回结果中选择模型名。

聊天请求

使用模型广场显示的准确模型 ID；请求体和可用参数以模型能力为准。

生产接入

服务端保存 Key，设置超时、重试和日志脱敏；前端浏览器不直接暴露长期 Key。

查询当前 Key 可用的模型（Bash）

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

Codex、Cursor、Cline 与兼容客户端

支持自定义 OpenAI 兼容 Base URL 的工具可以按同一套配置接入。工具界面名称可能不同，含义保持一致。

Base URL

https://api.bluedoai.com/v1

API Key

填写在小蓝助手控制台创建的 Key，不填写网站登录密码。

Model

填写模型广场或 GET /models 返回的准确模型 ID。

验证方法

先在工具内发一条短请求，再到控制台用量页确认调用记录。

进入

模型与算力

小蓝助手展示和分发当前公开模型能力，底层算力由合作 TokenHub 统一调度。平台不承诺所有上游模型长期可用，也不把上游宣传口径当作小蓝助手的固定承诺。

文本与对话

适合问答、写作、总结、翻译和办公任务，具体模型按模型广场的当前目录选择。

推理与编程

适合代码、分析和复杂任务；上下文、速度和计费以具体模型配置为准。

图片、语音和视频

只有模型广场显示并且当前 Key 有权限时才可调用，接口形态和返回时间可能与聊天接口不同。

算力消耗

调用消耗从小蓝助手账户余额和用量中记录，充值、余额和明细在控制台查看。

进入

错误排查

先记录请求时间、路径、模型名和状态码，再按下面顺序检查。不要提交完整 API Key。

401

检查 Authorization 头、Key 是否复制完整、Key 是否已停用，以及请求是否发到了 https://api.bluedoai.com/v1。

404

检查路径是否重复拼接了 /v1，或把聊天、Responses、多模态路径混用。

429 或余额错误

检查账户余额、模型权限和并发限制；到控制台查看充值与用量记录。

进入

5xx 或超时

记录时间和响应 request id，降低并发后重试；持续异常请通过联系我们提交脱敏信息。

进入

安全边界

文档只说明公开接入方式，不承载账号、供应商后台或密钥操作。

密钥

不要把 Key 提交到 Git、前端代码、日志、截图或工单。泄露后立即在控制台停用并重新创建。

数据

业务系统应自行确认发送内容、留存周期和访问权限，按最小必要原则接入。

计费

本页不固定写死价格；模型价格、倍率和余额以模型广场及控制台实时信息为准。

进入

请求测试与基本使用

先用短请求验证网络、鉴权和模型 ID，再接入业务代码。每次测试都应能在控制台用量记录中对应到时间和模型。

第一步：列出模型

调用 GET /models，确认当前 Key 可见的模型 ID；不要根据旧配置或上游页面猜测模型名。

第二步：短文本请求

使用少量输入和较小输出上限验证响应格式、状态码和 request id，确认成功后再增加上下文。

流式输出

客户端支持 stream 时按其 SDK 约定读取事件；不支持时使用普通 JSON 响应。具体字段以接口返回为准。

重试原则

只对网络超时和明确的临时 5xx 做有限次重试；401、403、404、余额不足和参数错误应先修正请求。

多模态接口

图片、向量、语音和视频属于按模型开放的能力。先在模型广场确认模型、输入格式和权限，再使用对应路径；聊天接口的参数不能直接套用到所有任务。

图片生成

使用 POST /images/generations，并按当前图片模型要求提交提示词、尺寸和输出格式；没有对应模型或权限时会返回错误。

向量嵌入

使用 POST /embeddings，输入文本或数组格式以模型能力为准，返回向量维度也可能随模型变化。

语音与视频

语音合成和视频任务的路径、异步状态和结果地址按当前公开接口返回判断；未在模型广场显示的能力不要直接上线依赖。

文件与隐私

发送图片、音频、视频或业务文件前确认数据授权、大小限制、保存周期和返回地址的访问权限。

SDK 与开发工具

运行 Python 和 Node.js 示例前，将控制台 Key 保存为 XIAOLAN_API_KEY，将 GET /models 返回的准确模型 ID 保存为 XIAOLAN_MODEL。Java 示例使用 Java 17 标准 HTTP 客户端，并需替换模型 ID 占位符。SDK 版本、参数命名和流式读取方式以工具自身文档为准。

Python、Node.js、Java

在客户端构造函数或配置文件中设置 base_url=https://api.bluedoai.com/v1、服务端 Key 和模型 ID；不要把 Key 写入前端或提交到仓库。

Codex CLI、Cursor、Cline

在工具的兼容 API 设置中填写 Base URL、Key 和 Model，先发一条短请求，再到控制台用量页核对记录。

进入

OpenClaw 等工具

只在工具支持自定义 OpenAI 兼容端点时接入；字段名称可能是 base URL、endpoint 或 api base，保存后以实际请求结果为准。

服务端部署

通过环境变量或密钥管理器注入 Key，设置请求超时、并发上限、日志脱敏和失败告警。

Python（pip install openai）

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["XIAOLAN_API_KEY"], base_url="https://api.bluedoai.com/v1")
response = client.chat.completions.create(
    model=os.environ["XIAOLAN_MODEL"],
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

Node.js（npm install openai，保存为 chat.mjs）

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.XIAOLAN_API_KEY,
  baseURL: 'https://api.bluedoai.com/v1',
});
const response = await client.chat.completions.create({
  model: process.env.XIAOLAN_MODEL,
  messages: [{ role: 'user', content: '你好' }],
});
console.log(response.choices[0].message.content);

Java 17 标准 HTTP 客户端（将占位模型 ID 改为可用 ID）

import java.net.URI;
import java.net.http.*;

public class ChatExample {
  public static void main(String[] args) throws Exception {
    String body = """
      {"model":"REPLACE_WITH_MODEL_ID","messages":[{"role":"user","content":"你好"}]}
      """;
    HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.bluedoai.com/v1/chat/completions"))
      .header("Authorization", "Bearer " + System.getenv("XIAOLAN_API_KEY"))
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(body)).build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode() + " " + response.body());
  }
}

计费与用量

计费由小蓝助手账户、模型配置和当前倍率共同决定。页面中的价格、余额和明细会变化，正式接入前以模型广场和控制台的实时信息为准。

模型价格

不同模型可能按输入、输出、图片、音频、视频或任务结果计费；具体单位和倍率以模型广场当前展示为准。

进入

余额与充值

充值入口、到账状态和账户余额在控制台查看；支付完成后以订单状态和余额变化为准，不要只依据浏览器提示判断。

进入

用量记录

按时间、模型和请求记录核对消耗；排查异常时保留时间、状态码和 request id，不要提交完整 Key。

进入

预算控制

在业务侧设置单次输出上限、并发限制和月度预算，发现余额或用量异常时先停用 Key，再联系平台处理。

平台特性与当前边界

上游 TokenHub 文档中的能力不等于小蓝助手已经对所有账户开放。下列特性只有在当前模型、账户权限和接口返回同时支持时才能使用。

请求路由

模型请求由小蓝助手网关按当前配置转发到可用算力；路由、限流和可用区可能随平台运行状态调整。

Fallback

只有在平台或模型页面明确显示并且接口返回支持时，才能依赖备用模型或自动降级；业务方应处理模型变化和响应差异。

异步推理

长任务可能返回任务 ID 或处理中状态。是否支持轮询、回调、结果保存和重试，以对应模型接口的实际响应为准。

语义缓存

平台是否启用缓存、缓存命中条件和计费处理以当前平台配置为准；敏感内容不要因为可能缓存而跳过业务侧脱敏。

常见问题

遇到问题时先保留脱敏后的请求信息，再按状态码定位。不要在工单、截图或聊天中发送完整 Key。

为什么返回 401？

确认使用的是小蓝助手 API Key、Authorization 头格式正确、Key 未停用，并且请求发往 https://api.bluedoai.com/v1。

为什么模型不存在？

先重新调用 GET /models 或打开模型广场，使用当前账户可见的准确模型 ID；旧模型名、别名和上游名称可能已经变化。

为什么请求很慢？

检查输入长度、模型类型、并发量和任务是否异步；记录 request id 后降低并发重试，持续异常请联系我们。

进入

文档能力都能用吗？

不能直接这样推断。以模型广场、当前 Key 权限和接口实际响应为准，未显示或未授权的能力不应写入生产依赖。

开发者入口

调用示例

示例只展示调用格式，请使用你在控制台创建的真实 API Key。

curl https://api.bluedoai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"模型广场中的模型 ID","messages":[{"role":"user","content":"你好"}]}'