SandBase 开发者文档sandbaseai/sandbase-docs

SandBase 文档

为 LLM、图像、视频、音频、真实世界 API 和可复用 Agent 提供统一的 API 接口。

文档 ·
商店 ·
控制台 ·
CLI / MCP ·
博客

SandBase 帮助开发者构建 AI 应用和 Agent 工作流，无需为每个模型、媒体生成器、搜索提供商或数据 API 维护单独的集成。

如果这些文档帮助你交付了一个集成，请考虑为仓库加星，并在问题跟踪器中分享一个经过脱敏的示例，以便其他开发者可以复现它。

使用最适合当前任务的最小接口：

| 需求 | 从这里开始 |
|---|---|
| OpenAI 兼容的 LLM 和视觉调用 | Chat Completions API |
| 图像、视频或音频任务 | 模型 API 参考 |
| 搜索、抓取、社交、商业或其他外部数据 | 商店 |
| 可复用、带版本的 Agent 工作流 | Agents |
| Codex、Claude Code、Cursor 和其他 AI 客户端 | 连接 AI 工具 |

目录、schema、价格和可用性可能会发生变化。请以实时商店和 API 参考作为事实来源，而不是猜测模型或 API 标识符。

开源配套项目

本文档是一个小型、可互操作的开源技术栈的一部分：

- SandBase CLI — 通过本地 MCP 桥接，将 25 个 AI 客户端
目标连接到当前的 SandBase 模型和 API 目录；
当前版本列在
官方 MCP Registry 中。
- SandBase Skills — 安装
将可复用的研究、营销和业务工作流转化为兼容的智能体。
- DeepSeek Harness Handbook
— 使用有来源支撑的指南来操作和扩展智能体运行时。

选择与你正在构建的层级相匹配的项目；上述链接作为规范的贡献和问题入口进行维护。
如果这个轻量级桥接能节省设置时间，请为 SandBase CLI 加星，
让更多智能体开发者发现它。

在本地构建和贡献

已发布的站点使用 VitePress 从本仓库构建。要在提交拉取请求之前预览文档更改：

npm ci
npm run dev

要进行与生产环境等效的检查，请运行 npm run validate；它会验证 OpenAPI 文档，检查已撤回的沙箱 API 是否未被暴露，并将生成的站点写入 .vitepress/dist。请将模型 ID、请求字段和定价与链接的实时参考页面保持一致，当事实来源不明确时请提交 issue。请查看仓库的未解决问题，了解当前的部署和内容工作。

生产部署

生产环境使用 Cloudflare Workers 静态资源独立于主网站进行部署。
该 Worker 仅拥有 www.sandbase.ai/docs 和
www.sandbase.ai/docs/；www.sandbase.ai 上的其他所有路由继续
使用现有的主站点源。

npm ci
npm run build:cloudflare
npx --yes wrangler@4.126.0 deploy

VitePress 构建将 /docs/ 保留为其公共基础 URL。一个小的 Worker 会在从 .vitepress/dist 读取生成的文件之前剥离
该前缀，而配置的路由确保它永远不会接收到非文档流量。GitHub Actions
从匹配 docs-v 的标签或从 main 手动触发进行部署，使用受保护的 production 环境和以下机密：

- CLOUDFLARE_API_TOKEN，其作用域为在
sandbase.ai 区域中部署该 Worker 并管理其路由

非机密的 Cloudflare 账户 ID 保存在工作流中，这样贡献者
无需仅仅为了识别部署账户而获得组织仪表板访问权限。

健康检查仍可在 https://www.sandbase.ai/docs/health 访问。

首次 LLM 调用

在控制台中创建 API 密钥，将其导出，并从支持的模型中选择一个当前模型 ID。

export SANDBASE_API_KEY="sk-YOUR_API_KEY"

curl https://api.sandbase.ai/v1/chat/completions \
-H "Authorization: Bearer $SANDBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek/deepseek-v4-flash",
"messages": [
{"role": "user", "content": "Explain this API response."}
]
}'

OpenAI SDK 应用程序可以通过更改 API 密钥、基础 URL 和模型来使用同一端点：

import os
from openai import OpenAI

client = OpenAI(
api_key=os.environ["SANDBASE_API_KEY"],
base_url="https://api.sandbase.ai/v1",
)

response = client.chat.completions.create(
model="deepseek/deepseek-v4-flash",
messages=[{"role": "user", "content": "Explain this API response."}],
)

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

兼容性可减少迁移工作；但它并不会让每个模型、参数、流式事件或提供商特定功能都完全相同。请遵循首次调用指南，并测试你的应用实际使用的行为。

运行模型或外部 API

图像、视频、音频和外部 API 操作使用每个 Store 详情页上记录的公共运行契约。模型/API 标识符和输入字段因操作而异。

curl -X POST https://api.sandbase.ai/v1/run \
-H "Authorization: Bearer $SANDBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_CURRENT_MODEL_OR_API_ID",
"YOUR_REQUIRED_INPUT": "value"
}'

不要将不同类型的工作负载强行纳入同一个响应生命周期：LLM 可能会流式输出 token，同步数据 API 可能会立即返回，而视频任务可能需要轮询或 webhook 处理。在集成所选能力之前，请检查其 schema 和执行模式。

连接 AI 客户端

开源 SandBase CLI 为 25 个 AI 客户端目标提供本地 MCP 桥接。请使用连接 AI 工具指南中的版本化安装命令，然后连接其中列出的确切客户端目标。

Skills 与执行仍然相互独立：

- SandBase Skills 打包可重复的工作流。
- CLI/MCP 桥接向兼容客户端暴露发现和执行工具。
- 当 Agents 需要持久会话、沙箱化工具、凭据、审计和重放时，SandBase Harness 是本地优先的运行时。

文档地图

| 部分 | 涵盖内容 |
|---|---|
| 入门 | API 密钥、快速开始和首次调用 |
| Store | 模型、API、Agents 和 Skills |
| 模型 | 支持的接口和能力指南 |
| API 参考 | 身份验证、Services、Schedules、Sessions、schema 和错误 |
| Agents | 可复用的 Agent 定义、Services、Sessions 和 Schedules |
| 设置 | 连接 AI 客户端并安装能力 |
| 面向 AI 工具 | 机器可读的集成指南 |
| 指南 | 流式传输、错误、速率限制和计费 |

仓库结构

getting-started/       # first-call onboarding
store/                 # 目录概念
models/                # 模型接口与能力
model-api-reference/   # 生成的模型与外部 API 参考
api-reference/         # REST API 契约
agents/                # 可复用的 Agent 工作流与服务
setup/                 # CLI 与客户端设置
for-agents/            # 简洁的机器可读指南
guides/                # 操作实践

本地开发

npm ci
npm run test:generator
npm run build
npm run dev

npm run test:generator 以及模型/API 参考生成器会从同级 sandbase-registry 检出目录
../sandbase-registry/data/ 读取带版本的目录。公开的 Docs 仓库并不内置该
目录。如果你只需要预览已生成的页面，npm run build
不需要同级检出目录；如果你要修改生成的参考文档，
请先准备好匹配的 registry 检出目录，并在提交其输出之前运行生成器。

本站点使用 VitePress 构建。生产部署由本仓库负责；请参阅 DEPLOYMENT.md。

贡献

发现了缺失的能力、失效的链接、不清晰的 schema 或过时的示例？请阅读贡献者指南，然后提交一个 issue 或提交一个聚焦的拉取请求。请勿在示例中包含 API 密钥、客户数据或提供商凭据。

许可证

Apache-2.0