문서
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
마이그레이션 가이드
마이그레이션은 1분도 채 걸리지 않습니다. 저희 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 업데이트
OpenAI key 대신 Smart AIPI key를 사용하세요. 그게 전부입니다!
Anthropic에서 이전
Smart AIPI API key 받기
회원가입 후 Dashboard에서 API key를 만드세요.
base URL 변경
다음을 교체하세요 https://api.anthropic.com 로 https://api.smartaipi.com
API key 업데이트
Anthropic key 대신 Smart AIPI 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를 포함해 실제 backend 모델을 완전히 투명하게 보여줍니다.
채팅 완료
제공된 messages와 model에 대해 chat completion을 생성합니다. 언어 모델과 상호작용하는 주요 endpoint입니다.
요청 본문 파라미터
| 파라미터 | 유형 | 필수 | 설명 |
|---|---|---|---|
| model | 문자열 | 예 | 사용할 모델 ID(예: "gpt-6-astra", "gpt-5.6-sol") |
| messages | 배열 | 예 | role과 content를 가진 message 객체 array |
| temperature | 숫자 | 아니요 | 샘플링 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는 기본적으로 reasoning.effort = "high" 을(를) 모든 Responses API 요청에 사용합니다.
광범위한 테스트 결과, 저희는 high 이(가) 실사용에 가장 적합한 reasoning effort라는 것을 확인했습니다. 이는 xhigh. 의 지연 비용 없이 깊고 신뢰할 수 있는 도구 사용과 분석을 제공합니다. 요청에서 reasoning effort를 명시적으로 설정해 이를 재정의할 수 있습니다.
Smart AIPI는 기본적으로 store = false 을(를) 모든 Responses API 및 WebSocket 요청에 사용합니다.
upstream 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 없음. thinking을 완전히 건너뜁니다.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이며, 서버 간 애플리케이션에서 Smart AIPI Realtime API에 연결하기에 좋은 선택입니다.
서버 간 통합에서는 backend 시스템이 WebSocket을 통해 Realtime API에 직접 연결합니다. 표준 API 키 을(를) 사용해 연결을 인증하세요. token은 보안이 유지된 backend 서버에서만 사용할 수 있기 때문입니다.
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 events로 관리됩니다. 요청을 response.create envelope로 감싸세요:
| 이벤트 | 방향 | 설명 |
|---|---|---|
| response.create | 클라이언트 | 요청 보내기(model, input, parameters를 감쌉니다) |
| response.created | 서버 | 세션 수락됨, 처리 시작 |
| response.output_text.delta | 서버 | streaming 텍스트 청크 |
| response.completed | 서버 | 전체 응답과 사용량이 포함된 terminal event |
| response.failed | 서버 | 오류를 나타내는 terminal event |
"store": false 이(가) 응답 envelope에 있어야 합니다. 연결은 여러 turn에 걸쳐 유지되므로 추가 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 protocol을 사용하는 앱이라면 어떤 것이든 사용할 수 있습니다. base URL만 바꾸면 됩니다.
지원 기능
- ✓ Streaming(전체 Anthropic SSE event protocol)
- ✓ 도구 사용 / function calling
- ✓ system messages(string 및 array 형식)
- ✓ 이미지 입력(base64 및 URL)
- ✓ Token 계산 (
/v1/messages/count_tokens) - ✓ 확장된 thinking / 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 모델 이름은 허용되며 tiered reasoning effort와 함께 GPT-5.4로 자동 라우팅됩니다. 모든 응답에는 x-actual-model header가 포함되어 실제 backend 모델을 보여줍니다.
| 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를 backend로 사용하여 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(high reasoning)를 사용합니다.ANTHROPIC_DEFAULT_HAIKU_MODEL— 백그라운드 모델입니다. 파일 인덱싱 같은 빠른 백그라운드 작업에 claude-haiku-4-5(low 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 backend로 사용하세요.
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"
}
코덱스 CLI
OpenAI의 Codex CLI 도구와 함께 Smart AIPI를 사용하세요. 세 개의 파일을 구성해야 합니다.
자동 설정
npx smart-aipi codex
이 설정은 아래 세 파일을 모두 자동으로 구성합니다. 실행 후 model_reasoning_effort 을(를) config에 추가하세요(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 수준: 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 속도 가이드
WebSocket mode는 도구 호출이 많은 agentic 코딩 흐름에서 보통 더 빠릅니다. HTTP로 반복 재연결하고 전체 요청 envelope를 다시 보내는 대신 Codex는 하나의 live connection을 유지하며 증분 turn을 보내 continuation 오버헤드를 줄입니다.
Codex에서 WebSockets 활성화
~/.codex/config.toml에서 WebSocket v2 기능 플래그를 사용하세요: ~/.codex/config.toml:
model = "gpt-6-astra"
model_reasoning_effort = "high"
[features]
responses_websockets_v2 = true
CLI 동등 명령:
codex --enable responses_websockets_v2
이전 빌드는 레거시 플래그를 사용할 수 있습니다:
[features]
responses_websockets = true
알려진 Homebrew 동작
일부 Homebrew 배포 빌드에서는 장시간 작업 중 WebSocket turn이 멈췄다가 조용히 HTTP로 fallback되는 경우가 있습니다. 특히 복잡한 tool-call 루프에서 이를 자주 확인했습니다. 아래 수정 사항을 적용해 오픈소스 코드에서 다시 빌드하면 안정성과 속도가 모두 개선되었습니다.
병합 후: 오픈소스 WebSocket 버그 수정
브랜치를 병합한 뒤, 이 체크리스트로 수정 사항이 로컬 바이너리에 반영되었는지 확인하세요:
# 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를 입력하세요
- 모델:
gpt-6-astra
Cline (VS Code)
- VS Code에서 Cline 설정 열기
- 선택하세요
OpenAI Compatible - 기본 URL:
https://api.smartaipi.com/v1 - API key를 입력하세요
- 모델:
gpt-6-astra
채팅
Smart AIPI Chat을 다음에서 사용하세요 chat.smartaipi.com. 텍스트, 이미지, 비디오, 코드, 검색, 음성 워크플로를 위해 사용할 수 있습니다.
기능
- ✓ 채팅 — Smart AIPI 모델로 범용 텍스트 대화를 수행합니다.
- ✓ 이미지 — prompts로 이미지를 생성하고 편집합니다.
- ✓ 비디오 — 텍스트 또는 이미지 입력으로 비디오를 생성합니다.
- ✓ 코드 — 브라우저에서 코드 지원 및 편집을 제공합니다.
- ✓ 검색 — 근거 있는 답변을 위해 웹 검색을 사용합니다.
- ✓ 음성 — 음성 입력과 응답으로 모델과 대화합니다.
시작하기
- 1. 열기 chat.smartaipi.com
- 2. 로그인하거나 계정을 만드세요.
- 3. 텍스트, 이미지, 비디오, 코드, 검색 또는 음성으로 채팅을 시작하세요.
과금: 사용량은 Smart AIPI 크레딧에서 차감됩니다.
API 테스터
브라우저에서 직접 API를 테스트해 보세요: