文档
Smart AIPI 同时提供兼容 OpenAI 和 Anthropic 的 API。你只需修改 base URL,即可将我们的服务接入任何现有的 OpenAI 或 Anthropic SDK、工具或应用。无需修改代码。
OpenAI 基础 URL
https://api.smartaipi.com/v1
Anthropic 基础 URL
https://api.smartaipi.com
CLI 和 MCP 工具
Smart AIPI 提供了两个 npm 包,帮助开发者操作他们的账户:
全部安装
npm install -g smart-aipi @smart-aipi/mcp
分别安装
npm install -g smart-aipi
npm install -g @smart-aipi/mcp
认证
所有 API 请求都需要 API key。同一个 key 可用于这两种认证方式:
Authorization: Bearer YOUR_API_KEY
x-api-key: YOUR_API_KEY
迁移指南
迁移不到一分钟即可完成。我们的 API 与 OpenAI 和 Anthropic endpoint 100% 兼容。
从 OpenAI 迁移
获取你的 Smart AIPI API key
注册并在你的 dashboard 中创建一个 API key。
修改 base URL
将 https://api.openai.com/v1 替换为 https://api.smartaipi.com/v1
更新你的 API key
使用你的 Smart AIPI key 替代 OpenAI key。就这么简单!
从 Anthropic 迁移
获取你的 Smart AIPI API key
注册并在你的 dashboard 中创建一个 API key。
修改 base URL
将 https://api.anthropic.com 替换为 https://api.smartaipi.com
更新你的 API key
使用你的 Smart AIPI key 替代 Anthropic key。你现有的 Claude 模型名称可直接继续使用。
你现有使用 Anthropic Messages API 的代码、SDK 和应用无需任何代码改动即可运行。Claude 模型名称 (claude-opus-4-6, claude-sonnet-4-5-20250929, claude-haiku-4-5-20251001) 会自动路由到高性能 GPT-5.4 模型。每个响应都包含一个 x-actual-model header,用于完整展示真实后端模型。
聊天完成
为给定的 messages 和 model 创建 chat completion。这是与语言模型交互的主要 endpoint。
请求体参数
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| model | 字符串 | 是 | 要使用的模型 ID(例如:"gpt-6-astra"、"gpt-5.6-sol") |
| messages | 数组 | 是 | 包含 role 和 content 的消息对象数组 |
| temperature | 数字 | 否 | 采样温度(0-2)。越高 = 越随机。默认:1 |
| max_tokens | 整数 | 否 | 响应中最多生成的 tokens 数量 |
| top_p | 数字 | 否 | Nucleus sampling。考虑 top_p 概率范围内的 tokens。默认:1 |
| frequency_penalty | 数字 | 否 | 根据频率惩罚 tokens(-2 到 2)。默认:0 |
| presence_penalty | 数字 | 否 | 根据出现情况惩罚 tokens(-2 到 2)。默认:0 |
| stop | 字符串/数组 | 否 | 停止序列。最多 4 个序列,生成在此处停止。 |
| stream | 布尔值 | 否 | 通过 SSE 启用 streaming 响应。默认:false |
消息角色
system- system - 设置 assistant 的行为/角色user- user - 来自用户的消息assistant- assistant - assistant 之前的回复
代码示例
from openai import OpenAI
client = OpenAI(
base_url="https://api.smartaipi.com/v1",
api_key="your-api-key"
)
response = client.chat.completions.create(
model="gpt-6-astra",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
],
temperature=0.7,
max_tokens=1000
)
print(response.choices[0].message.content)
Streaming
启用 streaming 后,可通过 Server-Sent Events (SSE) 在 tokens 生成时即时接收。这能为长响应提供更好的用户体验。
在你的请求中设置 "stream": true 以启用 streaming。
Streaming 示例
from openai import OpenAI
client = OpenAI(
base_url="https://api.smartaipi.com/v1",
api_key="your-api-key"
)
# Enable streaming
stream = client.chat.completions.create(
model="gpt-6-astra",
messages=[{"role": "user", "content": "Write a poem"}],
stream=True
)
# Process chunks as they arrive
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
推理强度
使用 reasoning_effort 参数来控制 GPT-5 模型的 reasoning 深度。
Smart AIPI 默认对所有 Responses API 请求使用 reasoning.effort = "high" 。
经过大量测试,我们发现 high 是最适合实际使用的 reasoning effort——它能在不承担 xhigh. 延迟成本的情况下,提供深入且可靠的工具使用与分析。你也可以在请求中显式设置 reasoning effort 来覆盖默认值。
Smart AIPI 默认对所有 Responses API 和 WebSocket 请求设置 store = false 。
上游 API 要求 store: false 用于 GPT-5.4 及更新模型。如果你显式设置了 store: true 在你的请求中,否则你会收到 "Store must be set to false" 错误。请移除它或将其设置为 false.
支持的模型
回复API
gpt-5.4、gpt-5.3、gpt-5.1、gpt-5,以及所有 Codex 变体
仅 Chat Completions
gpt-5.4-nano — reasoning 支持仅适用于 /v1/chat/completions 。
Reasoning Effort 等级
none- 无 reasoning。完全跳过思考。low- 最少 reasoning。非常适合简单任务。medium- 在速度和深度之间取得平衡。high- 适用于复杂问题的深度分析。 (Smart AIPI 默认值)xhigh- 额外高。为最困难的问题提供最大 reasoning 深度。
Fast Mode(优先处理)
使用 service_tier: "priority" 以获得更低延迟的优先处理。这也是 Codex CLI 中 /fast 命令所采用的模式。它不会改变 reasoning 深度——你获得相同质量,但速度更快。
价格: 优先处理按标准费率的 1.5 倍计费。例如,GPT-5.4 output 通常为 $3.75/1M tokens,启用优先处理后则为 $5.625/1M tokens。
response = client.responses.create(
model="gpt-6-astra",
input="Refactor this function",
service_tier="priority" # priority processing, lower latency
)
聊天完成 API
response = client.chat.completions.create(
model="gpt-6-astra",
messages=[{"role": "user", "content": "Analyze this code for bugs..."}],
reasoning_effort="high" # or "xhigh" for maximum depth
)
回复API
# Reasoning is set via the "reasoning" object
response = client.responses.create(
model="gpt-6-astra",
input=[{"role": "user", "content": "Refactor this function..."}],
reasoning={"effort": "high"} # defaults to "high" on Smart AIPI
)
图片生成
使用我们的图片生成 endpoint 根据文本 prompts 生成图片。
/v1/images/variations )暂不支持。图片编辑可通过 /v1/images/edits。
请求体参数
| 参数 | 类型 | 描述 |
|---|---|---|
| prompt | 字符串 | 要生成图片的文本描述(必填) |
| model | 字符串 | "gpt-image-2.5-flare"(frontier)、"gpt-image-2.5-sunburst" 或 "gpt-image-2"。默认:"gpt-image-2.5-flare" |
| n | 整数 | 要生成的图片数量(1-10)。默认:1 |
| size | 字符串 | "1024x1024"、"1024x1792" 或 "1792x1024"。默认:"1024x1024" |
| quality | 字符串 | "standard" 或 "hd"。默认:"standard" |
可用模型
gpt-image-2.5-flare- 前沿模型,质量最高(默认)gpt-image-2.5-sunburst- 精准编辑和高端创意工作(生成较慢)gpt-image-latest- gpt-image-2.5-flare 的别名gpt-image-2- 上一代旗舰模型gpt-image-1.5- 较旧的旗舰模型(支持透明背景)gpt-image-1- 全质量图片生成gpt-image-1-mini- 更快、更小尺寸的图片
示例
response = client.images.generate(
model="gpt-image-2.5-flare",
prompt="A futuristic city at sunset, cyberpunk style",
size="1024x1024",
n=1
)
# Response contains base64-encoded image
image_b64 = response.data[0].b64_json
# Save to file
import base64
with open("output.png", "wb") as f:
f.write(base64.b64decode(image_b64))
图片编辑
使用文本 prompt 编辑现有图片。支持 JSON(base64 字符串)和 multipart/form-data(文件上传),因此 OpenAI SDK 可开箱即用。
请求体参数
| 参数 | 类型 | 描述 |
|---|---|---|
| prompt | 字符串 | 期望编辑效果的文本描述(必填) |
| image | 字符串 | 要编辑的 base64 编码图片(必填) |
| model | 字符串 | "gpt-image-2.5-flare"(默认)、"gpt-image-2.5-sunburst" 或 "gpt-image-2" |
| n | 整数 | 要生成的编辑后图片数量(1-10)。默认:1 |
| size | 字符串 | "1024x1024"、"1024x1792" 或 "1792x1024"。默认:"1024x1024" |
| quality | 字符串 | "low"、"medium"、"high" 或 "auto"。默认值:"medium" |
image as an array of base64 strings (JSON) or as repeated image / image[] parts (multipart). Add a mask field alongside image to restrict edits to specific regions (white = edit, black = preserve). Works identically to the official OpenAI SDK.
示例
import base64
response = client.images.edit(
model="gpt-image-2.5-flare",
image=open("input.png", "rb"),
prompt="Change the background to a sunset beach",
size="1024x1024",
n=1
)
# Save the edited image
edited_b64 = response.data[0].b64_json
with open("edited.png", "wb") as f:
f.write(base64.b64decode(edited_b64))
通过 WebSocket 使用 Realtime API
WebSockets 是广泛支持的实时数据传输 API,也是 server-to-server 应用连接 Smart AIPI Realtime API 的理想选择。
在 server-to-server 集成中,你的后端系统会通过 WebSocket 直接连接到 Realtime API。请使用标准的 API 键 来认证连接,因为该 token 仅在你的安全后端服务器上可用。
通过 WebSocket 连接
下面提供了多个通过 WebSocket 连接的示例。除了使用 WebSocket URL 之外,你还需要使用 API key 传递一个认证 header。
import WebSocket from "ws";
const url = "wss://api.smartaipi.com/v1/responses";
const ws = new WebSocket(url, {
headers: {
Authorization: "Bearer " + process.env.SMARTAIPI_API_KEY,
},
});
ws.on("open", function open() {
console.log("Connected to server.");
// Send a response.create event
ws.send(JSON.stringify({
type: "response.create",
response: {
model: "gpt-6-astra",
store: false,
input: [{ role: "user", content: "Hello!" }],
stream: true,
},
}));
});
ws.on("message", function incoming(message) {
const event = JSON.parse(message.toString());
console.log(event.type, event);
});
发送和接收事件
会话通过 WebSocket 连接上的客户端发送和服务端发送 JSON 事件来管理。请将你的请求包裹在一个 response.create 封装中:
| 事件 | 方向 | 描述 |
|---|---|---|
| response.create | 客户端 | 发送请求(封装你的 model、input 和参数) |
| response.created | 服务端 | 会话已接受,处理已开始 |
| response.output_text.delta | 服务端 | Streaming 文本片段 |
| response.completed | 服务端 | 包含完整响应和 usage 的终止事件 |
| response.failed | 服务端 | 表示错误的终止事件 |
"store": false 在响应封装中。连接可跨多个 turns 持续存在——发送额外的 response.create frames,无需重新连接。
列出模型
获取所有可用模型的列表。使用此 endpoint 可动态发现你的账户可用哪些模型。
响应格式
{
"object": "list",
"data": [
{
"id": "gpt-6-astra",
"object": "model",
"created": 1700000000,
"owned_by": "smart-aipi"
},
{
"id": "gpt-5.3-codex",
"object": "model",
"created": 1700000000,
"owned_by": "smart-aipi"
},
// ... more models
]
}
示例
from openai import OpenAI
client = OpenAI(
base_url="https://api.smartaipi.com/v1",
api_key="your-api-key"
)
# List all available models
models = client.models.list()
for model in models.data:
print(model.id)
可用模型
GPT 系列
- gpt-6-astra 最新
- gpt-5.6-sol
- gpt-5.6-terra
- gpt-5.6-luna
- gpt-5.5
- gpt-5.4-pro
- gpt-5.4
- gpt-5.4-mini
- gpt-5.4-nano 仅 completions
Codex 系列
- gpt-5.3-codex
- gpt-5.2-codex
- gpt-5.2
- gpt-5.1
Anthropic 消息 API
完整兼容 Anthropic Messages API。可使用任意 Anthropic SDK、Claude Code 或任何支持 Anthropic 协议的应用——只需修改 base URL。
支持的功能
- ✓ Streaming(完整 Anthropic SSE 事件协议)
- ✓ 工具使用 / function calling
- ✓ System messages(字符串和数组格式)
- ✓ 图片输入(base64 和 URL)
- ✓ Token 计数 (
/v1/messages/count_tokens) - ✓ 扩展思考 / reasoning effort
代码示例
from anthropic import Anthropic
client = Anthropic(
base_url="https://api.smartaipi.com",
api_key="your-api-key"
)
response = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello!"}
]
)
print(response.content[0].text)
模型映射
支持 Claude 模型名称,并会自动路由到使用分层 reasoning effort 的 GPT-5.4。每个响应都包含一个 x-actual-model header,用于显示真实后端模型。
| Claude 模型 | 后端 | 推理 | 最适合 |
|---|---|---|---|
| claude-opus-4-6 | gpt-5.4 | 高 | 复杂 reasoning、架构设计 |
| claude-sonnet-4-5-20250929 | gpt-5.4 | 中 | 日常编码、质量均衡 |
| claude-haiku-4-5-20251001 | gpt-5.4 | 低 | 快速响应、简单任务 |
Claude Code
将 Smart AIPI 用作 Claude Code 的后端。完整支持工具使用、streaming 和 agentic 能力。
自动设置
npx smart-aipi claude
这会自动配置 ~/.claude/settings.json 和 ~/.claude.json 。如果你已经使用 Anthropic 账号配置了 Claude Code,它会向你显示手动配置,而不是直接覆盖。
手动设置
添加到 ~/.claude/settings.json:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.smartaipi.com",
"ANTHROPIC_API_KEY": "sk-your-key",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001"
},
"model": "opus"
}
然后添加 "hasCompletedOnboarding": true 到 ~/.claude.json 以跳过设置向导。
编辑设置后,请重启 Claude Code 使更改生效。如果你已经将 Claude Code 连接到真实的 Anthropic 账号,设置这些 env vars 会覆盖该连接——请使用项目级的 .claude/settings.json 以同时保留两者。
各项设置的作用
"model": "opus"— 主模型。使用 claude-opus-4-6(高 reasoning)处理所有主要任务。ANTHROPIC_DEFAULT_HAIKU_MODEL— 后台模型。使用 claude-haiku-4-5(低 reasoning)处理文件索引等快速后台任务。- 可在会话中途使用以下命令切换模型:
/model sonnet,/model opus, 或/model haiku.
| 别名 | Claude 模型 | 后端 | 推理 |
|---|---|---|---|
| opus | claude-opus-4-6 | gpt-5.4 | 高 |
| sonnet | claude-sonnet-4-5-20250929 | gpt-5.4 | 中 |
| haiku | claude-haiku-4-5-20251001 | gpt-5.4 | 低 |
OpenCode
通过兼容 OpenAI 的 SDK 将 Smart AIPI 用作你的 OpenCode 后端。
配置设置
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"smart-aipi": {
"npm": "@ai-sdk/openai-compatible",
"name": "Smart AIPI",
"options": {
"baseURL": "https://api.smartaipi.com/v1",
"apiKey": "YOUR_API_KEY"
},
"models": {
"gpt-6-astra": {
"name": "GPT-6 Astra",
"reasoning": true,
"limit": { "context": 400000, "output": 128000 }
},
"gpt-5.3-codex": {
"name": "GPT-5.3 Codex",
"reasoning": true,
"limit": { "context": 400000, "output": 128000 }
},
"gpt-5.2-codex": {
"name": "GPT-5.2 Codex",
"reasoning": true,
"limit": { "context": 400000, "output": 128000 }
},
"gpt-5-codex": {
"name": "GPT-5 Codex",
"reasoning": true,
"limit": { "context": 400000, "output": 128000 }
}
}
}
},
"model": "smart-aipi/gpt-6-astra"
}
法典 CLI
在 OpenAI 的 Codex CLI 工具中使用 Smart AIPI。需要配置三个文件。
自动设置
npx smart-aipi codex
这会自动配置下面三个文件。运行后,将 model_reasoning_effort 添加到你的配置中(见第 2 步)。
手动设置
请配置以下三个文件:
1. API 钥匙 — ~/.codex/auth.json
{
"auth_mode": "apikey",
"OPENAI_API_KEY": "sk-your-key"
}
2. 模型和 Reasoning — ~/.codex/config.toml
始终包含 model_reasoning_effort ——自定义模型必填。
如果没有它,Codex 默认不使用 reasoning,无法正常工作。建议使用 "high" 以获得最佳效果。
model = "gpt-6-astra"
model_reasoning_effort = "high"
有效的 reasoning levels: low, medium, high (推荐), xhigh.
3. 环境变量 — ~/.zshrc
# Smart AIPI
export OPENAI_API_KEY="sk-your-key"
export OPENAI_BASE_URL="https://api.smartaipi.com/v1"
编辑 shell profile 后,请重启终端或运行 source ~/.zshrc 使更改生效。
然后正常使用 Codex:
codex "fix this bug"
Codex WebSocket 速度指南
对于包含大量工具调用的 agentic 编码流程,WebSocket 模式通常更快。Codex 不再通过 HTTP 反复重连并重新发送完整请求封装,而是保持单个活动连接并发送增量 turns,从而减少 continuation 开销。
在 Codex 中启用 WebSockets
在 ~/.codex/config.toml 中使用 WebSocket v2 feature flag: ~/.codex/config.toml:
model = "gpt-6-astra"
model_reasoning_effort = "high"
[features]
responses_websockets_v2 = true
CLI 等价命令:
codex --enable responses_websockets_v2
较旧的构建可能使用旧版 flag:
[features]
responses_websockets = true
已知的 Homebrew 行为
在某些通过 Homebrew 分发的构建中,WebSocket turns 在长时间运行任务中可能会卡住,然后悄悄回退到 HTTP。我们在复杂的工具调用循环中尤其观察到了这一点。使用下面修复后的开源代码重新构建后,稳定性和速度都有所提升。
合并后:修复开源 WebSocket Bug
合并分支后,请使用这份清单确保修复已包含在你的本地二进制文件中:
# 1) Pull merged main
git checkout main
git pull --ff-only
# 2) Confirm websocket flags exist
codex features list | rg responses_websockets
# 3) Build and install
cd codex-rs
cargo build --release
install -m 0755 target/release/codex ~/.local/bin/codex-beta
# 4) Run with websocket enabled
CODEX_RS_RESPONSES_WS=true \
OPENAI_BASE_URL=https://api.smartaipi.com/v1 \
~/.local/bin/codex-beta --enable responses_websockets_v2
如果你需要手动打补丁,请确认以下代码级修复已存在:
# A) Build websocket request with IntoClientRequest so required headers are set
let mut request = url.as_str().into_client_request()?;
request.headers_mut().extend(headers);
# B) Ensure TLS roots are enabled for tokio-tungstenite in Cargo.toml
tokio-tungstenite = { version = "...", features = ["rustls-tls-native-roots"] }
Cursor 和 Cline
在 Cursor IDE 或 Cline VS Code 扩展中使用 Smart AIPI。
Cursor
- 打开 Cursor 设置
- 前往
Models选项卡 - 点击
+ Add Model - 设置 Base URL:
https://api.smartaipi.com/v1 - 输入你的 API key
- Model:
gpt-6-astra
Cline (VS Code)
- 在 VS Code 中打开 Cline 设置
- 选择
OpenAI Compatible - Base URL:
https://api.smartaipi.com/v1 - 输入你的 API key
- Model:
gpt-6-astra
聊天
在 chat.smartaipi.com. 使用 Smart AIPI Chat,支持文本、图片、视频、代码、搜索和语音工作流。
功能
- ✓ 聊天 — 使用 Smart AIPI 模型进行通用文本对话。
- ✓ 图像 — 根据 prompts 生成和编辑图片。
- ✓ 视频 — 通过文本或图片输入生成视频。
- ✓ 代码 — 在浏览器中进行代码辅助和编辑。
- ✓ 搜索 — 使用网页搜索获得有依据的答案。
- ✓ 语音 — 使用语音输入与模型对话,并获得语音回复。
快速开始
- 1. 打开 chat.smartaipi.com
- 2. 登录或创建一个账号。
- 3. 开始使用文本、图片、视频、代码、搜索或语音聊天。
计费: 使用量将从你的 Smart AIPI credits 中扣费。
API 测试器
直接在浏览器中测试 API: