O OneStepAI 帮助文档
VitePress 风格 · 面向最终用户

OneStepAI 帮助文档

这份文档按“注册账号、创建 Key、复制地址、直接调用”的顺序整理，适合第一次接入 OneStepAI 的用户，也适合已经在用 OpenAI SDK、Cherry Studio、Open WebUI、Dify、 FastGPT、Cline、Roo Code 一类客户端的用户快速迁移。

OpenAI Compatible Sub2API Powered 适合编程与工作流场景
打开 OneStepAI 控制台 直接看代码示例
01

一分钟上手

如果你只想先跑通一次请求，看这一段就够了。

最短路径

登录 dash.1step-ai.com， 创建 API Key，把 Base URL 填成 https://dash.1step-ai.com/v1，请求头带上 Authorization: Bearer 你的API Key，模型名使用控制台中当前可用的模型即可。

  1. 打开控制台并注册或登录账号。
  2. 如果你的账号没有余额或套餐，先完成充值、兑换或分配配额。
  3. 进入 API Keys 页面创建一个新的 Key。
  4. 在你的客户端或代码里填写 Base URL：https://dash.1step-ai.com/v1。
  5. 把请求头设置为 Authorization: Bearer 你的API Key。
  6. 把示例中的模型名替换成你控制台可见的模型后开始调用。
02

账号与控制台

先记住这三个地址，后面会频繁用到。

控制台

用于注册、登录、查看模型、创建 API Key、检查用量。

https://dash.1step-ai.com

文档站

就是当前这个帮助站，适合转给终端用户或团队成员。

https://doc.1step-ai.com

备用入口

适合对网络延迟或链路稳定性更敏感的场景。

https://api.1step-ai.com
注册说明

OneStepAI 当前面板支持注册、登录和支付能力。若你是由团队管理员分配账号，也可以直接登录后使用，不一定需要重新注册。

03

创建 API Key

大多数报错都和 Key 配置有关，建议第一次使用时手动新建一个。

  1. 登录 OneStepAI 控制台。
  2. 进入 API Keys 页面。
  3. 点击创建按钮，生成新的 API Key。
  4. 复制并保存这串 Key。通常它只会完整展示一次。
  5. 后续在客户端里统一使用这串 Key，不要混用登录密码。
注意

API Key 和账号密码不是一回事。代码、脚本、Cherry Studio、Open WebUI、Dify 一类应用，都应该填 API Key，而不是登录密码。

04

接口地址与鉴权

最容易填错的就是 Base URL 与 Host 的区别，这里一次说清楚。

填写场景 推荐填写 说明
Base URL / OpenAI API Base https://dash.1step-ai.com/v1 最常见的写法，适合 SDK、桌面客户端、工作流工具。
备用 Base URL https://api.1step-ai.com/v1 主地址网络不稳定时可以切换到这个备用地址。
只要求填 Host / Endpoint https://dash.1step-ai.com 只有当客户端会自动追加 /v1 时，才使用不带路径的域名。
鉴权方式 Authorization: Bearer YOUR_API_KEY 这是最推荐的写法，也最通用。
你只需要记住一件事

如果客户端是“OpenAI 兼容”模式，几乎总是优先填写 https://dash.1step-ai.com/v1。不要自己再额外拼接 /chat/completions 到 Base URL 里。

05

调用示例

下面的示例可以直接改 Key 之后测试。模型名请替换为你的控制台当前可用模型。

curl 测试聊天接口

curl https://dash.1step-ai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "messages": [
      {
        "role": "user",
        "content": "你好，帮我介绍一下 OneStepAI 的接入方式。"
      }
    ]
  }'

Python OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://dash.1step-ai.com/v1",
)

resp = client.chat.completions.create(
    model="YOUR_MODEL_NAME",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "请用三句话介绍 OneStepAI。"},
    ],
)

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

Node.js OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://dash.1step-ai.com/v1",
});

const completion = await client.chat.completions.create({
  model: "YOUR_MODEL_NAME",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "请给我一个接入检查清单。" },
  ],
});

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

先列出模型再调用

curl https://dash.1step-ai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
推荐做法

如果你不确定模型名，先调用一次 /v1/models，确认可用模型列表，再把示例中的 YOUR_MODEL_NAME 替换掉。

06

常用客户端配置

只要客户端支持 OpenAI 兼容模式或自定义 Base URL，通常都能接入。

客户端 / 工具 怎么选 核心配置
Cherry Studio 选择 OpenAI 兼容提供商或自定义提供商 Base URL 填 https://dash.1step-ai.com/v1，API Key 填你的 Key。
Open WebUI / LobeChat / NextChat 选择 OpenAI Provider API Host 或 Base URL 填 OneStepAI 地址，模型名按控制台实际可用列表填写。
Dify / FastGPT / LangChain 工作流 添加自定义 OpenAI 兼容模型供应商 建议优先使用 /v1 级别的 Base URL，不要把完整接口路径写进 Host。
Cline / Roo Code / Continue 等编程助手 选择支持自定义 OpenAI Endpoint 的模式 填入 Base URL、API Key、模型名即可，若不支持自定义地址则无法直接接入。
接入失败时先检查三件事

第一，看客户端到底要的是 Host 还是 Base URL；第二，确认是否已经填写 /v1；第三，确认客户端支持自定义 OpenAI 兼容接口，而不是强绑定官方 OpenAI 地址。

07

模型与使用建议

模型供应会随控制台配置变化，用户应以自己账号当前可见模型为准。

如何确认模型名

进入控制台查看模型列表，或直接调用 /v1/models。文档中的 YOUR_MODEL_NAME 只是占位符，不代表固定模型名。

如何选择地址

默认使用 https://dash.1step-ai.com/v1。如果出现链路不稳、超时、地区网络抖动，可切换到 https://api.1step-ai.com/v1 重试。

日常对话与轻量任务

选择更快、更省配额的轻量模型即可。适合常规问答、文本润色、简单脚本生成。

复杂编程与推理任务

选择你账户中性能更高的模型，尤其是长上下文、多文件分析、重构和复杂方案设计场景。

08

常见报错排查

大多数问题都能从报错文案里直接定位，下面是最常见的几类。

报错或现象 常见原因 处理建议
API_KEY_REQUIRED 没有带 Key，或请求头格式不对。 确认请求头为 Authorization: Bearer YOUR_API_KEY。
401 / 403 Key 无效、被禁用、复制时带了空格，或账号权限不足。 重新创建一个新的 API Key 进行测试，并检查账号状态。
404 / Not Found 地址写错，常见于漏掉了 /v1 或路径被重复拼接。 把 Base URL 改回 https://dash.1step-ai.com/v1 再试。
模型不存在 / model not found 模型名写错，或该模型当前账号不可见。 先请求 /v1/models，再用返回的模型名重新调用。
请求超时 / 网络波动 本地网络波动、代理链路不稳、地区访问不稳定。 切换到备用地址 https://api.1step-ai.com/v1 进行重试。
有 Key 但仍无法使用 账号无余额、套餐失效、配额耗尽，或客户端没有真的读到新配置。 检查控制台余额和订阅状态，并完全重启客户端后再试。
09

FAQ

把用户最容易反复问的问题集中放在这里，方便转发。

OneStepAI 支持哪些模型？

以你当前账号在控制台或 /v1/models 返回的列表为准。不同账号、不同套餐或不同时间段，模型可见范围可能不同。

为什么我已经填了 Key，还是提示未授权？

最常见原因是请求头格式错误。务必使用 Authorization: Bearer YOUR_API_KEY，不要只填 Key 本体，也不要把 Key 写到密码位置。

Base URL 为什么必须写到 /v1？

因为大多数 OpenAI 兼容客户端会在这个基础上继续拼接 /models 或 /chat/completions。如果你少了 /v1，通常就会直接 404。

主地址和备用地址有什么区别？

功能上没有本质区别，都是同一套 OneStepAI 服务入口。备用地址更适合主线路不稳定、网络绕路或延迟较高时切换使用。

哪些客户端不能直接接入？

凡是不支持自定义 OpenAI Base URL、不能自定义接口 Host，或者只能连接官方 OpenAI 的客户端，都不能直接接入 OneStepAI。

如果我是团队管理员，应该怎么把这份文档发给用户？

直接把 https://doc.1step-ai.com 发给用户即可。如果你希望降低沟通成本，也可以只截取“一分钟上手”和“常见报错排查”这两部分。

10

使用建议

最后补三条最实用的建议，基本能避开大部分新手问题。

  • 先用 /v1/models 确认模型，再接正式业务，能省掉很多模型名错误。
  • 把 Base URL 固定为 https://dash.1step-ai.com/v1，除非你明确知道客户端需要填 Host。
  • 如果遇到网络抖动或超时，优先切到 https://api.1step-ai.com/v1 进行交叉验证。
文档版本

当前页面基于 OneStepAI 已公开的控制台入口与兼容接口规则整理，适合作为用户接入手册与常见问题页面。