OpenAI 호환 API 가이드 — Ollama의 로컬 엔드포인트부터 호스팅 프런티어 모델까지

"OpenAI-compatible"는 API가 OpenAI의 /v1/chat/completions와 동일한 와이어 형식을 사용한다는 뜻입니다 — 따라서 base_url만 변경하면 모든 OpenAI SDK나 도구를 사용할 수 있습니다. Ollama는 컴퓨터에서 로컬로 실행되는 모델용 OpenAI 호환 엔드포인트를 제공합니다. Kunavo는 하나의 bearer token 뒤에서 호스팅된 프런티어 모델(Claude, GPT와 이미지·동영상·오디오 모델)을 제공합니다. 이 가이드에서는 코드를 다시 작성하지 않고 두 환경 사이를 이동하는 패턴을 설명합니다.

"OpenAI-compatible"의 의미

OpenAI Chat Completions 형식은 사실상 표준이 되었습니다. 입력으로 messages 배열을 받고, choices[].message을 출력하며, 스트리밍에는 Server-Sent Events를 사용하고, 함수 호출에는 tools를 사용합니다. 이 계약을 준수하는 모든 엔드포인트는 "OpenAI-compatible"이며, 공식 openai SDK(Python, Node 및 모든 커뮤니티 포트)는 base_url를 설정해 해당 엔드포인트를 가리킬 수 있습니다.

Ollama 패턴(로컬)

Ollama는 오픈 모델을 로컬에서 실행하고 http://localhost:11434/v1에서 제공합니다:

from openai import OpenAI

# Ollama exposes an OpenAI-compatible endpoint on localhost
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

resp = client.chat.completions.create(
    model="llama3.1",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

동일한 코드로 호스팅된 프런티어 모델 사용(Kunavo)

정확히 동일한 SDK를 Kunavo에 연결하고 프런티어 모델을 선택하세요. 변경되는 것은 base_url, api_key, model뿐이며 호출은 바이트 단위로 동일합니다:

import os
from openai import OpenAI

# Same SDK, same call shape — only base_url, api_key and model change
client = OpenAI(
    base_url="https://api.kunavo.com/v1",
    api_key=os.environ["KUNAVO_API_KEY"],
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-haiku-4-5, gpt-5-5, gpt-5-6-terra...
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

/app/keys에서 키를 발급받으세요. 빠른 시작에 Node 및 curl 형식이 있습니다.

로컬과 호스팅 — 언제 무엇을 사용할까

일반적인 구성은 오프라인 개발에는 localhost의 Ollama를, 프로덕션의 호스팅 품질에는 Kunavo를 사용하는 것입니다 — 환경 변수 하나로 전환됩니다. 양쪽이 구현하는 필드별 계약(매개변수, 스트리밍 델타, tool_calls, usage 객체 및 Ollama의 v1 인터페이스와의 호환성 표)은 /v1/chat/completions 레퍼런스와 Ollama OpenAI 호환성 섹션을 참고하세요.

런타임에 모델 검색하기

Ollama의 /api/tags처럼 Kunavo도 OpenAI 형식의 카탈로그를 제공합니다. 슬러그를 하드코딩하지 말고 런타임에 확인하세요:

# Discover every enabled model (OpenAI-shaped, like Ollama's /api/tags)
curl https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

채팅 외 기능

동일한 키로 이미지(/v1/images/generations), 동영상(/v1/video/generations), 오디오 엔드포인트에 연결할 수 있으며 모두 OpenAI 형식입니다. Kunavo가 다른 게이트웨이와 어떻게 다른지는 멀티모달 AI 가이드와 OpenRouter 비교를 참고하세요.

일반적인 "compatible"의 정의를 넘어서는 중요한 인터페이스가 하나 있습니다: POST /v1/responses. Codex CLI는 Responses API를 통해서만 사용자 지정 제공업체를 허용하므로 대부분의 OpenAI 호환 게이트웨이로는 Codex를 구동할 수 없습니다 — 토큰당 Codex 비용은 실행되는 구성 블록을 통해 이를 처리합니다. 캐시된 입력을 포함한 GPT 작업의 가격을 계산하려면 OpenAI API 가격 계산기에 직접 토큰 수를 입력하세요.

자주 묻는 질문