瑶瑶 API 开发者文档

1. 快速开始

如果你已经会用 OpenAI API，通常只需要替换 base_url 和 api_key 即可开始调用。

建议先用 curl 或 Python 示例完成一次最小调用，确认令牌、模型名、余额都正常，再把配置接入到自己的项目、客户端或自动化工作流里。这样排查问题最快，也能避免把模型名、Base URL、令牌分组混在一起调试。

2. 接入前准备

正式接入前，请准备好三个信息：账号余额、API Key、模型名称。余额用于支付模型调用费用，API Key 用于身份认证，模型名称决定请求会被路由到哪一类模型服务。

推荐环境变量

export OPENAI_API_KEY="sk-你的令牌"
export OPENAI_BASE_URL="https://api.yaoyao.chat/v1"

3. 创建 API Key / 令牌

1. 打开 API 控制台。
2. 进入 令牌管理 页面。
3. 点击 创建新的令牌。
4. 选择可用分组，例如 gptpro、claude 等，具体以后台显示为准。
5. 提交后复制 sk-... 格式的密钥。

令牌分组怎么选

令牌分组决定这把 API Key 能调用哪些模型。创建令牌时请选择当前页面中可用的分组；如果后续调用提示“无权限”或“模型不可用”，通常需要检查令牌分组是否支持对应模型。

令牌命名建议

建议用项目名或用途命名，例如 my-site-prod、dify-test、openwebui-home。这样在用量统计和问题排查时更容易判断是哪一个项目在调用。

API Key 相当于你的账户密码，请不要发给陌生人，也不要直接写在前端网页、App 或公开仓库里。

4. 接口地址

如果你的客户端有“API 地址”“Base URL”“接口地址”“OpenAI API Base”之类的输入框，通常填写 https://api.yaoyao.chat/v1。如果客户端要求填写完整接口路径，再按实际接口填写 /v1/chat/completions、/v1/responses 或 /v1/embeddings。

5. 认证方式

所有 API 请求都需要在请求头中携带 Bearer Token。令牌格式一般以 sk- 开头，请完整复制，不要添加多余空格或换行。

Authorization: Bearer sk-你的令牌
Content-Type: application/json

如果你使用官方 OpenAI SDK，只需要把 API Key 填到 SDK 配置里；SDK 会自动生成认证请求头。

不要把 API Key 放在浏览器前端代码里。网页、插件、小程序等前端场景建议通过自己的服务端转发请求。

6. 模型与价格

可用模型、上下文长度、分组、价格和状态会随供应商变化，请以 模型与价格页 为准。

选择模型时可以先按任务类型判断：日常问答、翻译、总结适合使用性价比高的通用模型；代码、复杂推理、长文档分析适合选择能力更强的模型；需要 Claude 风格输出或长文本处理时，可优先查看 Claude 相关分组。

常见填写方式：

{
  "model": "gpt-5.5",
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}

如果调用返回“模型不存在”或“无权限”，请检查：模型名是否拼写正确、令牌分组是否支持该模型、账户余额是否充足。

7. 常用请求参数

messages 结构

[
  {"role": "system", "content": "你是一个简洁、可靠的助手。"},
  {"role": "user", "content": "请帮我总结这段内容。"}
]

system 用来设置助手角色和回答风格，user 是用户输入，assistant 可用于保存历史回复，从而实现多轮对话。

8. curl 调用示例

curl https://api.yaoyao.chat/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "你好，请简单介绍一下你自己"}
    ]
  }'

返回示例

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "你好，我是一个 AI 助手。"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 12,
    "total_tokens": 30
  }
}

9. Python OpenAI SDK 示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的令牌",
    base_url="https://api.yaoyao.chat/v1"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "user", "content": "你好，请用一句话介绍瑶瑶 API"}
    ]
)

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

10. Node.js OpenAI SDK 示例

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-你的令牌",
  baseURL: "https://api.yaoyao.chat/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    { role: "user", content: "你好，请用一句话介绍瑶瑶 API" },
  ],
});

console.log(response.choices[0].message.content);

11. 流式输出 stream 示例

聊天产品通常需要边生成边显示，可以设置 stream: true。

Python 流式输出

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的令牌",
    base_url="https://api.yaoyao.chat/v1"
)

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "写一段简短欢迎语"}],
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="")

流式输出适合聊天窗口、写作工具、代码助手等场景。客户端需要逐段读取返回内容，并在前端持续追加显示。若你的框架暂时不支持流式处理，可以先使用普通非流式请求完成接入。

12. 多轮对话

多轮对话的关键是把历史消息一起传给模型。每次用户继续提问时，把必要的历史 user 和 assistant 消息保留下来，模型才能理解上下文。

{
  "model": "gpt-5.5",
  "messages": [
    {"role": "system", "content": "你是一个耐心的客服助手。"},
    {"role": "user", "content": "你们支持 Claude 吗？"},
    {"role": "assistant", "content": "支持，可以在模型与价格页查看可用 Claude 模型。"},
    {"role": "user", "content": "那我要怎么创建令牌？"}
  ]
}

历史消息越多，消耗的输入 token 越多。生产环境可以只保留最近几轮对话，或把长历史先总结成一段简短上下文。

13. Responses API

如果你的应用使用新版 OpenAI Responses API，可以尝试调用 /v1/responses。它适合更统一的文本生成、多模态输入和工具调用场景，具体能力以当前模型支持情况为准。

curl https://api.yaoyao.chat/v1/responses \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "请用三句话介绍瑶瑶 API"
  }'

如果你的 SDK 或客户端只支持 Chat Completions，继续使用 /v1/chat/completions 即可。

14. 计费与余额

平台会根据实际调用的模型、输入 token、输出 token 计算消耗。不同模型价格不同，请以 模型与价格页 为准。

15. 常见错误码与小白排查教程

接口报错时，不要先怀疑代码很复杂。大多数问题都可以按“地址、Key、模型、余额、频率”这 5 件事排查。你可以把错误信息复制下来，对照下面的表一步一步看。

最推荐的排查顺序

1. 先用最简单的问题测试：只发送一句 你好。如果简单问题都失败，先不要测试复杂代码或长文档。
2. 确认 Base URL 是 https://api.yaoyao.chat/v1。常见错误是只填了 https://api.yaoyao.chat，少了 /v1。
3. 重新复制 API Key。不要只看前几位，要完整复制整串 Key；复制后检查前后没有空格。
4. 确认模型名。请从模型与价格页复制模型名，例如 gpt-5.5 或对应 Claude 模型，不要手打。
5. 确认令牌分组。模型存在但无权限时，往往是 Key 所在分组不支持这个模型。
6. 确认余额。余额不足时，换模型也可能失败，因为所有调用都需要额度。
7. 如果是 429 或 5xx，先等一会儿再试；不要一直疯狂点击重试。

复制给客服或技术人员的信息模板

如果你排查后还不确定，可以把下面这段信息发给客服，处理会快很多：

我遇到 API 调用错误，请帮我看一下：
1. 报错状态码：
2. 完整错误提示：
3. 我填写的 Base URL：
4. 使用的模型名：
5. 大概发生时间：
6. 我是在什么工具里调用：例如 Cherry Studio / Dify / Python / Codex / Claude Code

不要把完整 API Key 发给任何人。需要截图时，可以只保留 Key 的前 6 位和后 4 位，中间用星号盖住。

最快自测命令

如果你会打开终端，可以用下面的命令测试。把 sk-你的令牌 换成自己的 Key：

curl https://api.yaoyao.chat/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "你好"}]
  }'

16. 限流与重试

调用模型接口时，偶尔会遇到上游繁忙、网络波动或并发限制。建议在业务代码中加入重试机制，尤其是后台任务、批量处理、自动化工作流等场景。

• 遇到 429 时，降低并发并等待几秒后再试。
• 遇到 500、502、503 时，可以进行 2 到 3 次指数退避重试。
• 不要对同一个失败请求无限重试，避免余额异常消耗。
• 聊天产品建议在前端展示“正在重试”或“请稍后再试”，提升用户体验。

// 伪代码
for (let i = 0; i < 3; i++) {
  try {
    return await callModel();
  } catch (error) {
    await sleep(1000 * Math.pow(2, i));
  }
}

17. 常用客户端配置教程

环境变量示例

export OPENAI_API_KEY="sk-你的令牌"
export OPENAI_BASE_URL="https://api.yaoyao.chat/v1"

18. API Key 安全建议

• 不要把 API Key 写进前端代码、公开仓库、截图或聊天记录。
• 生产环境建议由服务端代理请求，不要让浏览器直接调用。
• 如果怀疑密钥泄露，请立即在控制台删除旧令牌并创建新令牌。
• 建议为不同项目创建不同令牌，方便统计用量和排查问题。
• 注意查看调用日志和余额消耗，避免异常调用。

服务端代理建议

如果你在网页或 App 里使用 API，推荐让前端请求自己的后端，再由后端携带 API Key 调用瑶瑶 API。这样用户无法在浏览器控制台、抓包工具或安装包里直接看到你的密钥。

19. 上线检查清单

• Base URL 已统一配置为 https://api.yaoyao.chat/v1。
• API Key 没有写在前端代码、公开仓库或日志里。
• 模型名已按模型与价格页核对，令牌分组有对应权限。
• 业务代码已处理 401、402、403、429、500 等常见错误。
• 长对话已做历史裁剪或摘要，避免上下文过长。
• 生产环境已设置合理超时时间、重试次数和并发限制。
• 已准备余额不足、上游繁忙、模型切换等异常提示文案。

20. 常见问题

为什么提示模型不存在？

请先检查模型名是否和模型与价格页完全一致，再检查当前令牌分组是否支持该模型。

为什么提示无权限？

通常是令牌分组不匹配、令牌被禁用、账户余额不足或模型暂未开放。可以重新创建令牌并选择正确分组后再试。

为什么客户端连接失败？

最常见原因是 Base URL 填错。OpenAI 兼容客户端一般填写 https://api.yaoyao.chat/v1，不是首页地址，也不是控制台地址。

可以同时给多个项目用同一个 API Key 吗？

技术上可以，但不推荐。不同项目使用不同令牌，更容易统计用量、停用风险密钥和定位异常请求。

21. 常用入口