앱이 이미 OpenAI API와 통신하고 있다면 Kunavo로 전환하는 데 약 10분이면 됩니다. 대부분의 시간은 가입에 소요됩니다. 이 가이드에서는 대부분의 팀이 사용하는 네 가지 통합 방식과 각 방식에 필요한 한 줄 변경 사항을 설명합니다.
0단계 — 키 받기(2분)
- kunavo.com/app/signup에서 가입하세요. 10달러부터 충전할 수 있고, 사용한 만큼 지불하며 잔액은 만료되지 않습니다.
- /app/keys로 이동해 키를 생성하세요. 키는
sk-kn-로 시작합니다. - 환경 변수를 설정하세요:
export KUNAVO_API_KEY=sk-kn-....
1단계 — SDK 전환(1분)
Python(openai 패키지)
# Before — pointing at OpenAI directly
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"],
)
# After — pointing at Kunavo. Everything else stays the same.
from openai import OpenAI
client = OpenAI(
api_key=os.environ["KUNAVO_API_KEY"],
base_url="https://api.kunavo.com/v1",
)Node / TypeScript
// Before
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
// After
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.KUNAVO_API_KEY,
baseURL: "https://api.kunavo.com/v1",
});LangChain
LangChain은 내부적으로 동일한 OpenAI 클라이언트를 사용하므로 변경 사항도 동일합니다. 이제 모델 ID는 Kunavo 슬러그입니다. 최신 목록은 /models에서 확인하세요(claude-sonnet-4-6, gpt-5-6-terra, claude-opus-4-7를 사용해 보세요).
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="claude-sonnet-4-6", # switched the model
api_key=os.environ["KUNAVO_API_KEY"],
base_url="https://api.kunavo.com/v1",
)Vercel AI SDK
@ai-sdk/openai은(는) 기본적으로 환경 변수에서 기본 URL과 API 키를 읽습니다. 이를 설정하면 완료됩니다. 모든 프레임워크 도우미(streamText, generateObject, 재시도, 도구 라우팅)가 변경 없이 작동합니다.
import { openai } from "@ai-sdk/openai";
// @ai-sdk/openai reads OPENAI_BASE_URL automatically
process.env.OPENAI_BASE_URL = "https://api.kunavo.com/v1";
process.env.OPENAI_API_KEY = process.env.KUNAVO_API_KEY;
const model = openai("claude-sonnet-4-6");
// then use streamText / generateText / streamObject as beforeAnthropic SDK(이미 Claude를 사용 중인 경우)
Kunavo는 OpenAI 형식뿐 아니라 /v1/messages에서 Anthropic의 네이티브 Messages API도 제공합니다. 따라서 SDK를 전환할 필요가 없습니다.
from anthropic import Anthropic
# Before — Anthropic SDK against api.anthropic.com
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
# After — same SDK, against Kunavo. Caching, thinking, tools all pass through.
client = Anthropic(
api_key=os.environ["KUNAVO_API_KEY"],
base_url="https://api.kunavo.com", # SDK appends /v1/messages
)2단계 — 지갑 스모크 테스트(1분)
프로덕션 코드를 수정하기 전에 claude-haiku-4-5에 저렴한 테스트를 실행하세요. 성공적으로 반환되면 키, 결제, 라우팅 계층이 모두 정상적으로 작동하는 것입니다.
# Cheap, deterministic-ish smoke test for migration validation.
resp = client.chat.completions.create(
model="claude-haiku-4-5", # the cheapest Claude
messages=[{"role": "user", "content": "ping"}],
max_tokens=8,
temperature=0,
)
assert resp.choices[0].message.content, "empty response"
print("ok — Kunavo wallet works, total cost ~$0.0001")3단계 — 트래픽 이전(5분)
안전한 방식은 앱에서 환경별로 선택되는 두 개의 환경 변수(AI_BASE_URL 및 AI_API_KEY)를 사용하는 것입니다. 프로덕션은 OpenAI에 유지하고 스테이징만 Kunavo로 전환하세요. 24시간 후 프로덕션도 전환하면 됩니다.
전환 전에 비용 영향을 확인하고 싶다면 Kunavo 대시보드에서 호출별 비용과 공식 업스트림 요금을 비교할 수 있습니다. 실제 프롬프트를 기준으로 예상 월간 절감액을 쉽게 계산할 수 있습니다.
그대로 유지되는 것
- SDK와 코드베이스.
- 스트리밍, 함수 호출, 도구 사용, 비전, 구조화된 출력.
- OpenAI의 정확한 요청 및 응답 스키마.
- 오류 형식(
error.message/error.type/error.code).
더 나아지는 것
- 가격. 가격과 이용 가능한 할인은 모델에 따라 다릅니다. 현재 요금은 /pricing에서 확인하세요.
- 모달리티. 동일한 SDK로 Claude(
claude-opus-4-7), GPT(gpt-5-6-sol), GPT-Image-2, Nano Banana, Veo 3, Suno에 연결할 수 있습니다. /models를 참조하세요. - 결제. Stripe 지갑, USD 기준 가격. 모든 지역에서 카드 사용 가능; 인도를 제외한 모든 지역에서 Apple Pay, Google Pay 및 Link 사용 가능; 국가별 현지 결제 수단 제공(중국의 Alipay 및 WeChat Pay, 미국의 Cash App Pay, Klarna 및 ACH, 인도의 UPI, 한국의 KakaoPay 등) — 전체 목록은 /docs/billing에서 확인할 수 있습니다.
- 페일오버. 업스트림에 문제가 생기면 동일한 요청 안에서 자동으로 재라우팅되는 멀티벤더 핫 페일오버를 제공합니다.
원활하지 않은 경로에 대한 참고 사항
- 현재 지원하지 않는 OpenAI 전용 엔드포인트:
/v1/responses(/v1/chat/completions사용),/v1/assistants(상태는 사용자 측에서 관리하세요. Kunavo는 상태 비저장 게이트웨이입니다),/v1/realtime(예정). - 일부 Claude 전용 기능(
cache_control, 확장된thinking)은 OpenAI 형식이 아니라 네이티브 /v1/messages 엔드포인트를 통해 사용하는 것이 가장 좋습니다.
막히셨나요? contact@kunavo.com으로 문의하세요. 영업일 기준 하루 안에 담당자가 답변합니다. 본격적인 마이그레이션이라면 통화도 진행해 드립니다.