짧은 답변
base_url 및 api_key 두 가지 인자로 클라이언트를 생성하고, 이미 알고 있는 메서드를 계속 사용하세요. 이 API의 기본 URL은 https://api.apicompatible.com/v1이며, 모델 ID는 uncensored입니다. 인증은 SDK가 키에서 생성하는 표준 Bearer 토큰입니다.
from openai import OpenAI
client = OpenAI(
base_url="https://api.apicompatible.com/v1",
api_key="YOUR_API_KEY",
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Name three uses for a hash map."},
],
)
print(resp.choices[0].message.content)
print(resp.usage)
이것이 전체 변경 사항입니다. SDK는 base URL에 /chat/completions을 추가하므로 요청은 POST /v1/chat/completions에 도달합니다. 아직 키가 없다면 API 키 페이지에서 가입 방법과 체험 크레딧에 대해 설명합니다.
환경 변수를 사용하여 기본 URL 설정
공식 Python SDK는 코드에서 전달하지 않을 때 환경에서 OPENAI_API_KEY 및 OPENAI_BASE_URL을 읽습니다. 동일한 애플리케이션이 개발 및 프로덕션 환경에서 다른 엔드포인트에서 실행되거나, 타사 도구가 클라이언트를 생성하고 생성자 인자를 편집할 수 있는 위치를 제공하지 않는 경우에 유용합니다.
export OPENAI_BASE_URL="https://api.apicompatible.com/v1"
export OPENAI_API_KEY="YOUR_API_KEY"
python - <<'EOF'
from openai import OpenAI
client = OpenAI()
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Say hello in five words."}],
)
print(r.choices[0].message.content)
EOF
명시적 인수가 환경 변수보다 우선합니다. 호출이 잘못된 호스트로 가는 경우 코드에서 다른 부분이 자체 base_url로 클라이언트를 생성하는지, 그리고 .env 로더가 스크립트가 변수를 읽기 전에 실행되는지 확인하세요.
키를 소스 컨트롤에서 분리하세요. 환경 변수나 시크릿스 매니저에 있는 키는 쉽게 교체할 수 있지만, 커밋된 파일에 있는 키는 그렇지 않습니다.
Node에서의 동일한 변경 사항
Node 패키지는 동일한 옵션에 camel case를 사용합니다. 메서드 이름과 응답 형태를 포함하여 나머지 모든 내용은 OpenAI 형식 엔드포인트에 대해 작성하는 내용과 일치합니다.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.apicompatible.com/v1",
apiKey: process.env.API_KEY,
});
const completion = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Give me a one-line commit message for a typo fix." }],
});
console.log(completion.choices[0].message.content);
SDK 없이 원시 HTTP 확인을 위해 다음 curl 호출은 동일한 요청을 보내며 SDK 문제와 키 문제를 분리하는 데 유용합니다:
curl https://api.apicompatible.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"ping"}]}'
스트리밍, 비동기 및 재시도
스트리밍은 서버 전송 이벤트를 사용하며, SDK는 이를 반복자로 변환합니다. stream=True를 전달하고 도착하는 대로 델타를 읽으세요. 사용량 숫자는 스트림 끝에 도착하므로 텍스트가 없는 청크에 대비하세요.
from openai import OpenAI
client = OpenAI(
base_url="https://api.apicompatible.com/v1",
api_key="YOUR_API_KEY",
)
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Explain idempotency in two sentences."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
print()
비동기 클라이언트는 동일한 두 인자를 사용합니다. OpenAI를 AsyncOpenAI로 바꾸고, await을 추가하며 스트림에 async for를 사용하세요.
동시 요청을 여러 개 실행할 때 두 가지 한도가 중요합니다. 전체 키는 동시 요청 8개와 분당 300개 요청을 허용하며, 체험 키는 각각 2개와 60개를 허용합니다. 스트리밍 요청은 스트림이 완료될 때까지 동시 슬롯을 유지하므로 스트림을 비우지 않고 멈춘 클라이언트는 슬롯을 낭비합니다. 한도를 초과하면 오류 코드 rate_limited 또는 concurrency와 함께 HTTP 429를 받습니다. SDK는 기본적으로 실패한 요청을 몇 번 다시 시도하며, 클라이언트에서 max_retries를 변경할 수 있습니다. Retry-After: 5 헤더가 있는 429는 일시적 과부하를 의미하므로 5초 기다리는 것이 올바른 대응입니다.
타임아웃, 클라이언트 재사용 및 전송된 내용 디버깅
클라이언트를 한 번 생성하고 재사용하세요. 각 클라이언트는 자체 연결 풀을 유지하므로 매 요청마다 새 클라이언트를 생성하면 시간이 낭비되고 스트리밍 코드를 이해하기 어려워집니다. 아래 두 옵션은 생성자에 설정되며 해당 클라이언트를 통해 이루어지는 모든 호출에 적용됩니다.
from openai import OpenAI
client = OpenAI(
base_url="https://api.apicompatible.com/v1",
api_key="YOUR_API_KEY",
timeout=60.0,
max_retries=2,
)
긴 생성은 시간이 걸릴 수 있으므로 매우 짧은 타임아웃은 서비스 오류처럼 보이는 오류를 생성합니다. 가장 긴 예상 답변에 맞는 타임아웃을 선택하고 큰 출력의 경우 이를 높이세요.
요청이 사용한 URL 또는 키를 알 수 없는 경우 SDK의 디버그 로깅을 활성화하세요. 최신 Python 패키지는 OPENAI_LOG 환경 변수를 읽으며, 이를 debug로 설정하면 요청 행과 응답 상태가 출력됩니다. 현재 SDK 문서를 확인하여 버전별 정확한 동작을 확인하고, 로그에 민감한 데이터가 포함될 수 있으므로 이후 변수를 제거하세요. 출력된 호스트는 api.apicompatible.com이어야 합니다. 다른 값이 표시되면 다른 클라이언트 인스턴스나 환경 변수가 설정을 재정의하고 있습니다.
시간을 절약하는 마지막 습관: base URL, 키 및 모델 ID를 하나의 구성 모듈에 유지하세요. 세 가지가 한 곳에 있으면 엔드포인트 전환이 단일 편집 및 검토로 이루어집니다.
첫 번째 호출을 깨뜨리는 실수
대부분의 첫 번째 호출 실패는 짧은 원인 목록에서 비롯됩니다. 서비스를 의심하기 전에 순서대로 확인하세요.
base URL에 /v1이 누락되었거나 잘못된 경로가 있음
SDK는 엔드포인트 이름만 추가하므로 기본 URL은 /v1로 끝나야 합니다. 버전 구분자가 없는 https://api.apicompatible.com를 사용하거나 전체 /v1/chat/completions 경로를 붙여넣으면 최종 URL이 잘못되어 보통 404 오류가 발생합니다. SDK가 해결한 URL이 확실하지 않다면 client.base_url을 출력하세요.
모델 ID가 여전히 다른 공급업체의 이름임
이 API는 하나의 모델만 제공하며 그 ID는 uncensored입니다. 이전 설정에서 남은 모델 이름은 오류의 빈번한 원인이며, 이름이 코드 대신 구성 파일에 있을 때는 놓치기 쉽습니다. 프로젝트에서 이전 문자열을 검색하세요.
키가 잘못된 곳에서 가져옴
다른 공급업체의 키는 여기서 작동하지 않으며, 그 반대도 마찬가지입니다. OPENAI_API_KEY과 명시적 api_key을 모두 설정하면 명시적 값이 사용됩니다. 클라이언트에 도달한 값이 무엇인지 확인하세요.
이 API가 제공하지 않는 엔드포인트를 호출함
API는 텍스트 전용입니다. /v1/chat/completions, /v1/responses, /v1/models을 제공합니다. 이미지, 오디오, 임베딩 엔드포인트와 파인튜닝이 없어 해당 코드는 기존 제공업체에 남아야 합니다. 비용 및 트레이드오프 분석은 이러한 분할이 타당한 경우를 다룹니다.
페이로드가 너무 큼
최대 요청 본문 크기는 8 MB입니다. 긴 컨텍스트는 프롬프트와 완성의 합계가 100,000 토큰까지 괜찮지만, base64 블롭이나 큰 파일 붙여넣기는 먼저 본문 한도에 도달할 수 있습니다.
연결 및 잔액 확인
애플리케이션 코드를 디버깅하기 전에 GET /v1/models을 호출하세요. 깨끗한 목록은 키와 URL이 정확함을 의미합니다. 모든 응답에는 X-Balance-USD 헤더가 포함되어 있어 별도 호출 없이 지출을 모니터링할 수 있습니다. Python SDK에서는 with_raw_response를 사용하여 헤더를 읽으세요:
from openai import OpenAI
client = OpenAI(
base_url="https://api.apicompatible.com/v1",
api_key="YOUR_API_KEY",
)
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "ping"}],
)
print(raw.headers.get("X-Balance-USD"))
print(raw.headers.get("X-Request-Id"))
completion = raw.parse()
print(completion.choices[0].message.content)
지원에 연락할 때 X-Request-Id 값을 유지하세요. 이는 정확한 요청을 식별합니다. 실패하거나 거부된 요청에는 요금이 부과되지 않으므로 잘못된 호출은 비용이 들지 않습니다. 가격은 선불 크레딧 기준 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50입니다. 가격 책정 페이지에 세부 정보가 있으며 문서에는 모든 매개변수가 나열되어 있습니다.
