SandBase 开发者文档 sandbaseai/sandbase-docs

SandBase 文档

一套 API 接口，覆盖 LLM、图像、视频、音频、真实世界 API 和可复用智能体。

文档 ·商店 ·控制台 ·命令行 / MCP ·博客

SandBase 帮开发者构建 AI 应用和智能体工作流，不必为每个模型、媒体生成器、搜索服务商或数据 API 单独维护一套集成。

如果这些文档帮你交付了某个集成，欢迎给仓库点个 star，并在 issue tracker 里分享一份脱敏示例，方便其他开发者复现。

按任务选最小的接口面：

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

目录、schema、价格和可用性都可能变化。以线上商店和 API 参考为准，不要猜模型或 API 标识符。

开源配套项目

这套文档属于一个小型、可互操作的开源栈：

- SandBase 命令行 —— 通过本地 MCP 桥接，把 25 个 AI 客户端目标连接到当前的 SandBase 模型和 API 目录；当前版本列在官方 MCP Registry 中。
- SandBase 技能 —— 安装把可复用的研究、营销和业务工作流接入兼容的智能体。
- DeepSeek Harness Handbook
— 阅读有来源支撑的指南，了解如何运维和扩展智能体运行时。

按你正在构建的层次选择项目；上面的链接是官方维护的贡献与问题入口。
如果这个轻量桥接能帮你省下配置时间，欢迎给 SandBase CLI 点星，让更多智能体开发者发现它。

本地构建与贡献

已发布的站点由本仓库用 VitePress 构建。想在提交 pull request 前预览文档改动：

npm ci
npm run dev

要做与生产环境一致的检查，运行 npm run validate；它会校验 OpenAPI 文档、检查已下线的沙箱 API 是否仍被暴露，并把生成的站点写入 .vitepress/dist。模型 ID、请求字段和定价请以链接的在线参考页为准；来源不明确时请开 issue。当前部署与内容工作请见仓库的 open issues。

生产部署

生产环境独立于主站部署，使用 Cloudflare Workers Static Assets。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/ 作为公开 base URL。一个小 Worker 会先剥掉这个前缀，再从 .vitepress/dist 读取生成的文件；配置好的路由保证它永远收不到非文档流量。GitHub Actions 从匹配 docs-v 的 tag 部署，或从 main 手动触发，使用受保护的 production 环境和以下 secret：

- CLOUDFLARE_API_TOKEN，权限范围限定为在 sandbase.ai zone 内部署 Worker 并管理其路由

非机密的 Cloudflare account ID 放在 workflow 里，这样贡献者不必为了确认部署账号就去访问组织后台。

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

第一次调用 LLM

在 Console 创建 API key，导出它，再从 Supported Models 选一个当前模型 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 key、base URL 和模型，就能用同一个 endpoint：

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 操作都使用公开的 run 契约，具体文档见每个 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 提供本地 MCP 桥接，支持 25 个 AI 客户端目标。使用连接 AI 工具指南中的带版本安装命令，然后连接其中列出的确切客户端目标。

技能与执行保持分离：

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

文档地图

| 章节 | 内容 |
| 入门 | API 密钥、快速开始和首次调用 |
| Store | 模型、API、智能体和技能 |
| 模型 | 支持的接口和能力指引 |
| API 参考 | 认证、Services、Schedules、Sessions、schema 和错误 |
| 智能体 | 可复用的智能体定义、Services、Sessions 和 Schedules |
| 安装 | 连接 AI 客户端并安装能力 |
| 面向 AI 工具 | 机器可读的集成指引 |
| 指南 | 流式传输、错误、速率限制和计费 |

仓库结构

getting-started/ # first-call onboarding
store/ # 目录概念 models/ # 模型接口与能力 model-api-reference/ # 生成的模型与外部 API 参考 api-reference/ # REST API 契约 agents/ # 可复用的智能体工作流与服务 setup/ # 命令行与客户端设置 for-agents/ # 面向机器的简明指引 guides/ # 运维实践

本地开发 bash
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 或提交一个聚焦的 pull request。示例里不要包含 API 密钥、客户数据或服务商凭据。

许可证

Apache-2.0