문서
← 모든 문서

문서

인증

Kunavo의 인증 방식은 OpenAI와 동일합니다. Authorization 헤더에 단일 Bearer 토큰을 넣으면 됩니다. 일반적인 OpenAI 통합과 다른 점은 기본 URL뿐입니다.

모든 API 호출은 Authorization: Bearer sk-kn-XXX 헤더를 포함해 https://api.kunavo.com/v1로 전송됩니다. 그게 전부입니다.

기본 URL

모든 모델과 모든 모달리티를 제공하는 단일 엔드포인트입니다.

필드값
기본 URLhttps://api.kunavo.com/v1
리전미국 애시번(Ashburn)이 기본 리전이며 다중 리전 엣지가 요청을 처리합니다.
TLSTLS 1.2 이상을 강제합니다. HTTPS만 허용합니다.

경로 구조는 OpenAI 규칙을 따릅니다:

모달리티경로
채팅POST /v1/chat/completions
모델 목록GET /v1/models
이미지 생성POST /v1/images/generations
이미지 편집 / i2iPOST /v1/images/edits
동영상 생성POST /v1/video/generations
TTSPOST /v1/audio/speech
음악POST /v1/audio/music

API 키

대시보드의 /app/keys에서 API 키를 발급합니다. 각 키는 다음과 같습니다.

  • sk-kn-로 시작하며 뒤에 30자 이상의 무작위 문자가 붙습니다.
  • 생성 시 한 번만 표시됩니다. 이후 Kunavo에는 해시만 저장됩니다.
  • 대시보드에서 알아보기 쉬운 이름이 있습니다(예: prod-web).
  • 언제든지 폐기할 수 있으며, 폐기 즉시 해당 키에 401 오류가 반환됩니다.
  • 키마다 월별 지출 한도와 IP 허용 목록을 설정할 수 있습니다. 둘 다 /app/keys에서 설정하며 모든 호출에 적용됩니다.

키별 지출 한도(선택 사항)

각 키에 월별 지출 한도를 달러로 설정할 수 있습니다. 해당 키의 현재 달력 기준 월의 정산된 사용량이 한도를 초과하게 되면 월초에 한도가 초기화될 때까지 해당 키로 보낸 호출은 402 insufficient_quota를 반환하며 요금이 청구되지 않습니다. 다른 키에는 영향이 없습니다. 계정 전체가 아니라 특정 인증 정보 하나에 적용되는 상한입니다.

이 설정은 무인 에이전트에 필요한 통제 수단입니다. 지갑 잔액은 모든 키가 공유하므로 그 자체로는 폭주하는 루프 하나가 잔액을 전부 쓰는 것을 막을 수 없습니다. 에이전트 전용 키를 만들고 작업 규모에 맞는 한도를 설정하면 최악의 경우에도 지출은 해당 금액으로 제한됩니다. 한도를 $0로 설정하면 키를 폐기하지 않고도 사용을 일시 중지할 수 있습니다.

키별 IP 허용 목록(선택 사항)

키를 특정 주소 집합에서만 사용할 수 있도록 제한할 수도 있습니다. IPv4/IPv6 주소 또는 CIDR 블록을 한 줄에 하나씩 입력하세요(203.0.113.7, 198.51.100.0/24, 2001:db8::/32). 다른 곳에서 해당 키로 호출하면 403 permission_error가 반환되며, /v1/models를 포함한 모든 엔드포인트에 적용됩니다. 비워 두면 모든 주소를 허용합니다.

확인하는 주소는 엣지 프록시가 관찰한 주소이며 클라이언트가 헤더에서 주장하는 주소가 아닙니다. 따라서 X-Forwarded-For를 위조해 허용 목록을 우회할 수 없습니다. 반대로 호출자가 새 호스트, NAT 게이트웨이 또는 네트워크로 이동하면 허용 목록이 설정된 키는 즉시 작동을 멈춥니다. 허용 목록은 송신 주소가 안정적인 서버에 설정하고 노트북에는 설정하지 마세요.

요청 헤더

최소 요청에는 다음 두 헤더가 포함됩니다.

Authorization: Bearer sk-kn-...
Content-Type: application/json

모든 엔드포인트는 Authorization 대신 x-api-key 헤더에서도 키를 읽습니다. Anthropic SDK가 보내는 헤더이므로 Anthropic API용 클라이언트도 사용자 지정 헤더 없이 /v1/models를 포함한 모든 경로에 연결할 수 있습니다. 요청에 두 헤더가 모두 있으면 Authorization를 사용합니다. 키의 지출 한도와 IP 허용 목록은 어떤 헤더로 키를 전달하든 적용됩니다.

선택 사항이지만 권장합니다. 앱을 식별하는 User-Agent입니다. 요청 출처를 디버깅할 수 있도록 /app/usage 대시보드에 사용자 에이전트를 기록합니다.

OpenAI SDK 사용하기

대부분의 팀은 공식 OpenAI SDK를 그대로 사용하고 base_url만 바꿉니다. Python(v1.x+)과 Node(v4.x+) 모두 이 방식으로 사용할 수 있습니다.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KUNAVO_API_KEY"],
    base_url="https://api.kunavo.com/v1",
)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});
OpenAI SDK는 Node에서 baseURL, Python에서 base_url를 사용합니다. 둘 다 같은 엔드포인트를 가리킵니다.

키 교체

권장 사항: API 키를 분기별로 또는 키 유출 가능성이 있을 때마다 교체하세요. Kunavo에서는 계정당 여러 키를 동시에 사용할 수 있으므로 기존 키와 새 키를 겹쳐 운영하며 원활하게 교체할 수 있습니다.

# 1. Create a new key in /app/keys, set its name to e.g. "prod-2026-Q2"
# 2. Deploy new key to your servers
# 3. Verify traffic is flowing on the new key (dashboard shows usage)
# 4. Revoke the old key from /app/keys → it 401s immediately

# In code, swap one env var:
export KUNAVO_API_KEY="sk-kn-new-..."
키를 폐기하면 즉시 401 오류가 반환됩니다. 유예 기간은 없습니다. 기존 키를 폐기하기 전에 새 키로 트래픽이 흐르는지 확인하세요.

보안 참고 사항

  • 키를 클라이언트 측에 노출하지 마세요. 브라우저 코드와 모바일 번들은 공개됩니다. 항상 서버를 통해 프록시하세요.
  • 키의 권한 범위를 좁게 설정하세요. 프로젝트마다 서로 다른 키를 사용하면 다른 워크로드에 영향을 주지 않고 키를 폐기할 수 있습니다. 키마다 자체 지출 한도와 IP 허용 목록도 설정할 수 있으므로 유출된 키의 비용과 사용 출처를 제한할 수 있습니다.
  • 대시보드를 확인하세요. /app/usage 페이지에서 키별로 분류된 트래픽을 볼 수 있어 예상치 못한 활동을 쉽게 발견할 수 있습니다.
  • 유출이 의심되면 신고하세요. support@kunavo.com으로 이메일을 보내 주시면 키 무효화와 사고 검토를 도와드립니다.

다음 단계