키 발급과 첫 호출
키를 발급받고 5분 안에 첫 응답을 받아 봅니다.
키 발급하고 설정하기
게이트웨이는 쿠키도 세션도 쓰지 않습니다. API 키 화면에서 키를 하나 발급받아 Authorization 헤더에 담아 보내면 그걸로 끝입니다.
키 발급
API 키 화면에서 키 발급을 누릅니다.
평문 키는 한 번만 보입니다
발급 직후 화면에 뜨는 sk-proj-… 는 그때 한 번만 보입니다. 못 받아 적었으면 다시 발급하세요 — 이전 키는 그 즉시 막힙니다.
주소와 키를 환경변수로
키는 코드에 박지 말고 환경변수로 둡니다. 저장소에 올라간 키는 유출된 키입니다.
GATEWAY_URL=https://ai.cubion.kr
GATEWAY_KEY=sk-proj-... # /app/keys 에서 발급 — 발급 직후 한 번만 보입니다첫 호출로 키 확인
아무것도 만들기 전에 GET /v1/models 를 한 번 불러 봅니다. 요금이 들지 않고, 키가 살아 있는지와 이 키로 쓸 수 있는 모델이 무엇인지를 한 번에 알려 줍니다.
curl https://ai.cubion.kr/v1/models \
-H "Authorization: Bearer $GATEWAY_KEY"
# 200 이면 키가 살아 있는 것입니다. 401 이면 키가 틀렸거나 폐기된 키입니다.import os
from openai import OpenAI
client = OpenAI(
base_url="https://ai.cubion.kr/v1", # 여기만 바꾸면 됩니다
api_key=os.environ["GATEWAY_KEY"],
)
for m in client.models.list().data:
print(m.id)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://ai.cubion.kr/v1", // 여기만 바꾸면 됩니다
apiKey: process.env.GATEWAY_KEY,
});
const models = await client.models.list();
for (const m of models.data) console.log(m.id);{
"object": "list",
"data": [
{ "id": "gpt-4o", "object": "model", "owned_by": "openai", "mode": "chat" }
],
"key": { "name": "내 키", "scopes": ["ai"], "restricted": false }
}인증과 baseURL
게이트웨이는 OpenAI 호환입니다. 이미 OpenAI SDK 를 쓰고 있다면 바꿀 것은 두 줄 — baseURL 과 apiKey 뿐입니다.
- 인증은 헤더 하나입니다:
Authorization: Bearer sk-proj-…(쿠키·세션 없음) - baseURL 은
https://ai.cubion.kr/v1입니다. 경로와 요청·응답 형식은 OpenAI 와 같습니다. - 키가 유출된 것 같으면 API 키 에서 바로 폐기하세요. 폐기한 키로는 그 즉시 호출이 되지 않습니다.
잔액 확인
모델 목록은 무료지만 모델 호출은 잔액에서 차감됩니다. 잔액이 0원이면 다음 단계의 호출이 429 insufficient_balance 로 막히니 먼저 확인하세요.
curl https://ai.cubion.kr/v1/balance -H "Authorization: Bearer $GATEWAY_KEY"
# {"object":"balance","currency":"KRW","balance":3000,"low_balance":false,"topup_url":"…"}0원이라면
충전·결제 에서 사용량 패키지를 구매하면 즉시 반영됩니다. 키를 다시 발급할 필요는 없습니다.
첫 응답 받아 보기
키와 잔액이 확인됐으면 바로 모델을 부를 수 있습니다. 같은 코드에서 모델 이름만 바꾸면 OpenAI·Anthropic·Gemini 가 모두 호출됩니다.
curl https://ai.cubion.kr/v1/chat/completions \
-H "Authorization: Bearer $GATEWAY_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"안녕"}]}'r = client.chat.completions.create(
model="gpt-4o", # "claude-sonnet-4-5", "gemini/gemini-2.5-flash" 등
messages=[{"role": "user", "content": "안녕"}],
)
print(r.choices[0].message.content)const r = await client.chat.completions.create({
model: "gpt-4o", // "claude-sonnet-4-5", "gemini/gemini-2.5-flash" 등
messages: [{ role: "user", content: "안녕" }],
});
console.log(r.choices[0].message.content);모델 이름을 앱에 박아 두지 마세요. 쓸 수 있는 모델은 바뀔 수 있으니 모델 목록 으로 채우는 편이 안전합니다.
브라우저에서 부를 때
/v1/* 은 CORS 를 허용하므로 브라우저에서 직접 fetch 해도 동작합니다. 다만 동작하는 것과 안전한 것은 다릅니다.
브라우저에 올린 키는 공개된 키입니다
프런트엔드 코드에 넣은 키는 개발자 도구에서 그대로 보입니다. 개인 프로젝트나 내부 도구가 아니라면 키는 서버에만 두고, 브라우저는 여러분의 서버를 부르게 하세요.