Tài liệu

Smart AIPI cung cấp cả API tương thích OpenAI và Anthropic. Dùng dịch vụ của chúng tôi với bất kỳ OpenAI hoặc Anthropic SDK, công cụ hay ứng dụng hiện có nào chỉ bằng cách đổi base URL. Không cần thay đổi code.

Công cụ CLI & MCP

Smart AIPI cung cấp hai package npm để giúp developer làm việc với tài khoản của họ:

Cài cả hai

Cài riêng lẻ

Xác thực

Tất cả API request đều yêu cầu API key. Cùng một key hoạt động với cả hai phương thức xác thực:

Hướng dẫn chuyển đổi

Việc chuyển đổi mất chưa đến một phút. API của chúng tôi tương thích 100% với cả endpoint OpenAI và Anthropic.

Từ OpenAI

Từ Anthropic

Hoàn thành cuộc trò chuyện

Tạo chat completion cho messages và model được cung cấp. Đây là endpoint chính để tương tác với language models.

Tham số phần thân request

Vai trò của message

Ví dụ code

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)

import OpenAI from 'openai';

const openai = new OpenAI({
    baseURL: 'https://api.smartaipi.com/v1',
    apiKey: 'your-api-key'
});

const response = await openai.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
});

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

curl https://api.smartaipi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7,
    "max_tokens": 1000
  }'

package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("your-api-key")
    config.BaseURL = "https://api.smartaipi.com/v1"
    client := openai.NewClientWithConfig(config)

    resp, _ := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "gpt-6-astra",
            Messages: []openai.ChatCompletionMessage{
                {Role: "system", Content: "You are a helpful assistant."},
                {Role: "user", Content: "Hello!"},
            },
            Temperature: 0.7,
            MaxTokens:   1000,
        },
    )
    fmt.Println(resp.Choices[0].Message.Content)
}

use async_openai::{Client, config::OpenAIConfig};
use async_openai::types::{
    CreateChatCompletionRequestArgs, ChatCompletionRequestMessage,
    ChatCompletionRequestSystemMessageArgs, ChatCompletionRequestUserMessageArgs,
};

let config = OpenAIConfig::new()
    .with_api_key("your-api-key")
    .with_api_base("https://api.smartaipi.com/v1");

let client = Client::with_config(config);

let request = CreateChatCompletionRequestArgs::default()
    .model("gpt-6-astra")
    .messages([
        ChatCompletionRequestSystemMessageArgs::default()
            .content("You are a helpful assistant.")
            .build()?.into(),
        ChatCompletionRequestUserMessageArgs::default()
            .content("Hello!")
            .build()?.into(),
    ])
    .build()?;

let response = client.chat().create(request).await?;
println!("{}", response.choices[0].message.content);

Streaming

Bật streaming để nhận tokens ngay khi chúng được tạo qua Server-Sent Events (SSE). Điều này mang lại trải nghiệm người dùng tốt hơn cho các phản hồi dài.

Ví dụ 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="")

const stream = await openai.chat.completions.create({
    model: 'gpt-6-astra',
    messages: [{ role: 'user', content: 'Write a poem' }],
    stream: true,
});

for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content || '';
    process.stdout.write(content);
}

Mức độ Reasoning

Kiểm soát độ sâu reasoning bằng tham số reasoning_effort cho các model GPT-5.

Model được hỗ trợ

Các mức Reasoning Effort

Fast Mode (Xử lý ưu tiên)

Sử dụng service_tier: "priority" để xử lý ưu tiên với độ trễ thấp hơn. Đây là thứ mà lệnh /fast trong Codex CLI dùng đến. Nó không thay đổi độ sâu reasoning - bạn vẫn có cùng chất lượng, chỉ nhanh hơn.

response = client.responses.create(
    model="gpt-6-astra",
    input="Refactor this function",
    service_tier="priority"              # priority processing, lower latency
)

API Chat Completions

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
)

Phản hồi 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
)

Tạo ảnh

Tạo ảnh từ prompt văn bản bằng endpoint tạo ảnh của chúng tôi.

Tham số phần thân request

Các model có sẵn

Ví dụ

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))

curl https://api.smartaipi.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A futuristic city at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Chỉnh sửa ảnh

Chỉnh sửa ảnh hiện có bằng prompt văn bản. Hỗ trợ cả JSON (chuỗi base64) và multipart/form-data (upload file), nên OpenAI SDKs hoạt động ngay.

Tham số phần thân request

Ví dụ

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))

curl https://api.smartaipi.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change the background to a sunset beach" \
  -F "[email protected]" \
  -F "size=1024x1024" \
  -F "n=1"

Realtime API với WebSocket

WebSockets là một API được hỗ trợ rộng rãi cho truyền dữ liệu thời gian thực, và là lựa chọn tuyệt vời để kết nối tới Smart AIPI Realtime API trong các ứng dụng server-to-server.

Trong tích hợp server-to-server, hệ thống backend của bạn kết nối qua WebSocket trực tiếp tới Realtime API. Hãy dùng một phím API chuẩn để xác thực kết nối, vì token chỉ khả dụng trên backend server bảo mật của bạn.

Kết nối qua WebSocket

Dưới đây là một số ví dụ kết nối qua WebSocket. Ngoài việc dùng WebSocket URL, bạn cũng cần truyền header xác thực bằng API key của mình.

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);
});

import os, json, websocket

url = "wss://api.smartaipi.com/v1/responses"
headers = ["Authorization: Bearer " + os.environ["SMARTAIPI_API_KEY"]]

def on_open(ws):
    print("Connected to server.")
    ws.send(json.dumps({
        "type": "response.create",
        "response": {
            "model": "gpt-6-astra",
            "store": False,
            "input": [{"role": "user", "content": "Hello!"}],
            "stream": True,
        }
    }))

def on_message(ws, message):
    data = json.loads(message)
    print("Event:", data["type"])

ws = websocket.WebSocketApp(url, header=headers,
    on_open=on_open, on_message=on_message)
ws.run_forever()

# Verify WebSocket handshake (requires curl with --http1.1)
curl --max-time 5 --http1.1 -i -N \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: $(openssl rand -base64 16)" \
  "https://api.smartaipi.com/v1/responses"

# A successful handshake returns:
# HTTP/1.1 101 Switching Protocols
# upgrade: websocket
# sec-websocket-accept: ...

Gửi và nhận sự kiện

Các phiên được quản lý bằng các sự kiện JSON do client gửi và server gửi qua kết nối WebSocket. Gói request của bạn trong một response.create phong bì:

Danh sách model

Lấy danh sách tất cả model hiện có. Dùng endpoint này để khám phá động các model khả dụng cho tài khoản của bạn.

Định dạng phản hồi

{
    "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
    ]
}

Ví dụ

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)

curl https://api.smartaipi.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Các model có sẵn

Anthropic Tin nhắn API

Tương thích đầy đủ với Anthropic Messages API. Dùng bất kỳ Anthropic SDK, Claude Code hoặc ứng dụng nào dùng giao thức Anthropic - chỉ cần đổi base URL.

Tính năng được hỗ trợ

Ví dụ code

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)

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
    baseURL: 'https://api.smartaipi.com',
    apiKey: 'your-api-key'
});

const response = await client.messages.create({
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [
        { role: 'user', content: 'Hello!' }
    ]
});

console.log(response.content[0].text);

curl https://api.smartaipi.com/v1/messages \
  -H "x-api-key: your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello!"}
    ]
  }'

Ánh xạ model

Tên model Claude được chấp nhận và tự động định tuyến đến GPT-5.4 với reasoning effort theo tầng. Mỗi phản hồi đều bao gồm một x-actual-model header hiển thị model backend thực.

Claude Code

Dùng Claude Code với Smart AIPI làm backend. Hỗ trợ đầy đủ tool use, streaming và khả năng agentic.

Thiết lập tự động

npx smart-aipi claude

Thiết lập này sẽ tự động cấu hình ~/.claude/settings.json và ~/.claude.json Nếu bạn đã thiết lập Claude Code với tài khoản Anthropic, hệ thống sẽ hiển thị cấu hình thủ công thay vì ghi đè.

Thiết lập thủ công

Thêm vào ~/.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"
}

Sau đó thêm "hasCompletedOnboarding": true vào ~/.claude.json để bỏ qua trình hướng dẫn thiết lập.

Ý nghĩa của từng thiết lập

OpenCode

Dùng Smart AIPI làm backend OpenCode của bạn thông qua SDK tương thích OpenAI.

Thiết lập Config

{
  "$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"
}

Codex CLI

Dùng Smart AIPI với công cụ Codex CLI của OpenAI. Cần cấu hình ba file.

Thiết lập tự động

npx smart-aipi codex

Thiết lập này sẽ tự động cấu hình cả ba file dưới đây. Sau khi chạy, thêm model_reasoning_effort vào config của bạn (xem bước 2).

Thiết lập thủ công

Cấu hình ba file này:

1. API Chìa khóa — ~/.codex/auth.json

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-your-key"
}

2. Mô hình & Lý luận — ~/.codex/config.toml

model = "gpt-6-astra"
model_reasoning_effort = "high"

Các mức reasoning hợp lệ: low, medium, high (khuyên dùng), xhigh.

3. Biến môi trường — ~/.zshrc

# Smart AIPI
export OPENAI_API_KEY="sk-your-key"
export OPENAI_BASE_URL="https://api.smartaipi.com/v1"

Sau đó dùng Codex như bình thường:

codex "fix this bug"

Hướng dẫn tăng tốc Codex WebSocket

Chế độ WebSocket thường nhanh hơn cho các luồng lập trình agentic có nhiều tool call. Thay vì liên tục kết nối lại qua HTTP và gửi lại toàn bộ request envelope, Codex giữ một kết nối sống duy nhất và gửi các lượt tăng dần, giúp giảm overhead continuation.

Bật WebSockets trong Codex

Dùng cờ tính năng WebSocket v2 trong ~/.codex/config.toml: ~/.codex/config.toml:

model = "gpt-6-astra"
model_reasoning_effort = "high"

[features]
responses_websockets_v2 = true

Tương đương trong CLI:

codex --enable responses_websockets_v2

Các bản build cũ có thể dùng cờ legacy:

[features]
responses_websockets = true

Hành vi Homebrew đã biết

Trên một số bản build được phân phối qua Homebrew, các lượt WebSocket có thể bị treo trong các tác vụ chạy dài rồi âm thầm rơi về HTTP. Chúng tôi thấy điều này đặc biệt xảy ra trong các vòng lặp tool-call phức tạp. Build lại từ mã nguồn mở với các bản sửa bên dưới đã cải thiện cả độ ổn định lẫn tốc độ.

Sau khi merge: Sửa lỗi WebSocket mã nguồn mở trong Codex

Sau khi merge nhánh của bạn, dùng checklist này để đảm bảo bản sửa đã có trong binary cục bộ:

# 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

Nếu bạn cần vá thủ công, hãy xác minh các bản sửa cấp code này có mặt:

# 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"] }

Con trỏ & Cline

Dùng Smart AIPI với Cursor IDE hoặc extension Cline cho VS Code.

Trò chuyện

Sử dụng Smart AIPI Chat tại chat.smartaipi.com. cho các workflow văn bản, ảnh, video, code, search và giọng nói.

Tính năng

• ✓ Trò chuyện — Hội thoại văn bản đa dụng với các model Smart AIPI.
• ✓ Hình ảnh — Tạo và chỉnh sửa ảnh từ prompt.
• ✓ Băng hình — Tạo video từ văn bản hoặc hình ảnh đầu vào.
• ✓ Mã số — Hỗ trợ và chỉnh sửa code ngay trong trình duyệt.
• ✓ Tìm kiếm — Dùng tìm kiếm web để có câu trả lời bám sát thực tế.
• ✓ Giọng nói — Nói chuyện với model bằng giọng nói và nhận phản hồi bằng giọng nói.

Bắt đầu

Thanh toán: Mức sử dụng sẽ được tính vào credits Smart AIPI của bạn.

Trình kiểm tra API

Test API trực tiếp từ trình duyệt của bạn: