文档

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 包,帮助开发者操作他们的账户:

smart-aipi — 一个 CLI 工具,可让你通过终端以编程方式管理账户、API keys 和 usage。
@smart-aipi/mcp — 一个 MCP server,让 AI agents 直接访问你的 Smart AIPI 账户。

全部安装

终端
npm install -g smart-aipi @smart-aipi/mcp

分别安装

仅 CLI
npm install -g smart-aipi
仅 MCP
npm install -g @smart-aipi/mcp

认证

所有 API 请求都需要 API key。同一个 key 可用于这两种认证方式:

OpenAI 风格(Authorization header)
Authorization: Bearer YOUR_API_KEY
Anthropic 风格(x-api-key header)
x-api-key: YOUR_API_KEY

迁移指南

迁移不到一分钟即可完成。我们的 API 与 OpenAI 和 Anthropic endpoint 100% 兼容。

从 OpenAI 迁移

1

获取你的 Smart AIPI API key

注册并在你的 dashboard 中创建一个 API key。

2

修改 base URL

https://api.openai.com/v1 替换为 https://api.smartaipi.com/v1

3

更新你的 API key

使用你的 Smart AIPI key 替代 OpenAI key。就这么简单!

从 Anthropic 迁移

1

获取你的 Smart AIPI API key

注册并在你的 dashboard 中创建一个 API key。

2

修改 base URL

https://api.anthropic.com 替换为 https://api.smartaipi.com

3

更新你的 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。

POST /v1/chat/completions

请求体参数

参数 类型 必填 描述
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
POST /v1/images/generations
新功能:gpt-image-2.5-flare 和 gpt-image-2.5-sunburst 现已推出。 OpenAI 最新的图像模型现已上线:质量高于 gpt-image-2,延迟最高降低 50%(flare);并为生产级创意工作提供更精细的多轮编辑控制(sunburst)。令牌费率与 gpt-image-2 保持不变,因此此处价格完全相同——升级无需额外费用。两者均支持生成、编辑和蒙版修复,价格为 OpenAI 直销价格的 50%。 阅读发布文章.

请求体参数

参数 类型 描述
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 可开箱即用。

注意: 目前仅支持单图编辑。暂不支持多图输入和 mask 字段。
POST /v1/images/edits

请求体参数

参数 类型 描述
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"
Multi-reference edits and mask inpainting are supported. Pass 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 仅在你的安全后端服务器上可用。

WSS wss://api.smartaipi.com/v1/responses

通过 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 服务端 表示错误的终止事件
重要: WebSocket 请求必须包含 "store": false 在响应封装中。连接可跨多个 turns 持续存在——发送额外的 response.create frames,无需重新连接。

列出模型

获取所有可用模型的列表。使用此 endpoint 可动态发现你的账户可用哪些模型。

GET /v1/models

响应格式

{
    "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。

POST /v1/messages

支持的功能

  • 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:

~/.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 后端。

配置设置

~/.config/opencode/opencode.json
{
  "$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

~/.codex/auth.json
{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-your-key"
}

2. 模型和 Reasoning — ~/.codex/config.toml

始终包含 model_reasoning_effort ——自定义模型必填。

如果没有它,Codex 默认不使用 reasoning,无法正常工作。建议使用 "high" 以获得最佳效果。

~/.codex/config.toml
model = "gpt-6-astra"
model_reasoning_effort = "high"

有效的 reasoning levels: low, medium, high (推荐), xhigh.

3. 环境变量 — ~/.zshrc

~/.zshrc (or ~/.bashrc)
# 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 开销。

观察到的改进: 在我们大量工具调用的编码测试中,重新构建并修复 WebSocket 的开源 Codex,与 HTTP continuation 模式相比,端到端运行时间大约减少了 30-40%。

在 Codex 中启用 WebSockets

在 ~/.codex/config.toml 中使用 WebSocket v2 feature flag: ~/.codex/config.toml:

~/.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

如果你需要手动打补丁,请确认以下代码级修复已存在:

websocket 客户端修复
# 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

  1. 打开 Cursor 设置
  2. 前往 Models 选项卡
  3. 点击 + Add Model
  4. 设置 Base URL: https://api.smartaipi.com/v1
  5. 输入你的 API key
  6. Model: gpt-6-astra

Cline Cline (VS Code)

  1. 在 VS Code 中打开 Cline 设置
  2. 选择 OpenAI Compatible
  3. Base URL: https://api.smartaipi.com/v1
  4. 输入你的 API key
  5. Model: gpt-6-astra

聊天

chat.smartaipi.com. 使用 Smart AIPI Chat,支持文本、图片、视频、代码、搜索和语音工作流。

功能

  • 聊天 — 使用 Smart AIPI 模型进行通用文本对话。
  • 图像 — 根据 prompts 生成和编辑图片。
  • 视频 — 通过文本或图片输入生成视频。
  • 代码 — 在浏览器中进行代码辅助和编辑。
  • 搜索 — 使用网页搜索获得有依据的答案。
  • 语音 — 使用语音输入与模型对话,并获得语音回复。

快速开始

  1. 1. 打开 chat.smartaipi.com
  2. 2. 登录或创建一个账号。
  3. 3. 开始使用文本、图片、视频、代码、搜索或语音聊天。

计费: 使用量将从你的 Smart AIPI credits 中扣费。

API 测试器

直接在浏览器中测试 API:

消息已发送

我们会在 2 个工作日内回复你。

联系支持

有问题或需要帮助?给我们发消息,我们会在 2 个工作日内回复你。