API 레퍼런스

unbleep은 OpenAI Chat Completions API 형식을 그대로 씁니다. OpenAI를 호출해 본 적이 있다면 이 API는 이미 아는 것과 같습니다. 클라이언트를 https://unbleep.ai/v1으로 향하게 하고 키만 바꾸세요.

퀵스타트

OpenAI SDK를 설치하고 base URL과 키를 설정한 뒤 호출하면 됩니다.

python

from openai import OpenAI

client = OpenAI(
    base_url="https://unbleep.ai/v1",
    api_key="ub_live_9f2c…",
)

resp = client.chat.completions.create(
    model="unbleep",
    messages=[{"role": "user", "content": "Say hello."}],
)
print(resp.choices[0].message.content)

인증

모든 요청에는 Authorization 헤더에 Bearer 토큰이 있어야 합니다. 키에는 접두사가 붙어 있어 유출되더라도 시크릿 스캐너가 바로 알아볼 수 있습니다:

ub_live_… — 프로덕션용. 선불 크레딧에서 과금됩니다.
ub_test_… — 로컬 개발용. 라이브 키와 똑같이 과금됩니다. 토큰당 단가도 같고 같은 선불 크레딧에서 차감되며, 유일한 차이는 키당 속도 제한이 더 낮다는 점입니다(속도 제한 참고). 테스트 키는 별도로 폐기할 수 있는 자격 증명일 뿐, 무료 티어가 아닙니다.

헤더

Authorization: Bearer ub_live_9f2c…

키는 서버 쪽에만 두세요. 라이브 키를 브라우저나 모바일 코드에 넣어 배포하면 안 됩니다.

모델

아래 ID 중 하나를 model로 전달하세요. 날짜가 없는 별칭은 항상 최신 빌드를 가리키고, 날짜가 붙은 스냅샷 ID도 받아들이며 현재는 같은 빌드로 해석됩니다. 어느 형태로 보내든 응답에는 날짜 없는 ID가 실립니다. 예를 들어 unbleep-250811로 요청하면 "model": "unbleep"으로 돌아옵니다.

모델	별칭이 가리키는 빌드	컨텍스트	적합한 용도
unbleep	unbleep-250811	256K	일반 용도 — 기본값
unbleep-high	unbleep-high-250811	1M	가장 큰 작업 — 긴 문서 & 코드베이스 전체
unbleep-mini	unbleep-mini-250811	32K	저렴하고 빠른 대량 호출

Chat completions

POST /v1/chat/completions — 핵심 엔드포인트입니다. 요청과 응답 본문은 OpenAI 스키마와 동일합니다.

curl · 요청

curl https://unbleep.ai/v1/chat/completions \
  -H "Authorization: Bearer ub_live_9f2c…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "unbleep",
    "messages": [
      {"role": "system", "content": "You are terse."},
      {"role": "user", "content": "Explain abliteration in one line."}
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

json · 응답

{
  "id": "chatcmpl_a1b2c3",
  "object": "chat.completion",
  "model": "unbleep",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "…" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 24, "completion_tokens": 18, "total_tokens": 42 }
}

스트리밍

"stream": true를 설정하면 Server-Sent Events로 받습니다. 각 이벤트는 delta를 담은 chat.completion.chunk 하나이며, 스트림은 리터럴 data: [DONE]으로 끝납니다.

이벤트 스트림

data: {"choices":[{"delta":{"content":"Ab"}}]}
data: {"choices":[{"delta":{"content":"literation"}}]}
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]

추론

추론 모델은 답하기 전에 먼저 생각합니다. 그 사고 과정은 평소의 content 옆에 reasoning_content 필드로 돌아옵니다. 일반 호출에서는 message에, 스트리밍 중에는 delta에 실립니다. 이 필드는 모델이 실제로 사고 과정을 생성했을 때만 존재하므로 선택적 필드로 다루고, 답변 자체는 content에서 읽으세요.

json · 응답 일부

{
  "index": 0,
  "message": {
    "role": "assistant",
    "reasoning_content": "The question asks for one line, so…",
    "content": "…"
  },
  "finish_reason": "stop"
}

추론 토큰도 과금됩니다. 사고 과정은 생성된 출력이므로, 코드에서 이 필드를 읽든 읽지 않든 모델의 일반 출력 단가로 청구됩니다. 짧은 질문에 긴 숙고가 붙으면 그만큼 청구서에 실제 항목으로 잡힙니다.

"thinking": false를 보내면 추론이 꺼지고, 완성 토큰 예산이 사고 과정 대신 답변에 쓰입니다:

json · 요청 일부

{
  "model": "unbleep",
  "messages": […],
  "thinking": false
}

정책 다이얼

unbleep만의 차별점입니다. 선택 파라미터 policy는 요청에 얼마나 많은 거버넌스를 적용할지 정합니다. 기본값은 off입니다.

off — 필터 없는 기본 상태(기본값). 거부 응답을 주입하지 않습니다.
research — off와 정확히 같게 답합니다. 이 값은 사용량 기록 행에 남아 자체 보고용으로 쓸 수 있을 뿐, 추가 검사는 적용하지 않습니다.
strict — 메시지 텍스트를 서비스 차단 목록과 대조해 일치하면 정책 오류를 반환합니다. 차단 목록은 운영자가 관리하며 옵트인한 모든 사용자에게 동일하게 적용됩니다. 계정별로 설정할 수 있는 차단 목록은 없습니다.

json · 요청 일부

{
  "model": "unbleep",
  "messages": […],
  "policy": "research"
}

오류

오류는 OpenAI 엔벨로프 형식을 따르므로 기존 오류 처리 코드가 그대로 동작합니다.

json · 401

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "Incorrect API key provided."
  }
}

상태 코드	의미
401	키가 없거나 유효하지 않음
402	크레딧 소진 — 계속하려면 충전 필요
422	`policy: strict`에 의해 차단됨
429	속도 제한 — 잠시 후 재시도
5xx	업스트림 오류 — 백오프를 두고 재시도해도 안전

속도 제한

계정 단위로 서로 독립적인 두 가지 제한이 적용됩니다. 요청 속도와 동시 요청 상한입니다.

요청 속도

계정당 분당 60회 요청이며, 60초 슬라이딩 윈도로 측정합니다. 제한은 키가 아니라 계정에 걸립니다. 키를 더 만든다고 처리량이 늘지 않으며, 보유한 모든 키가 같은 60회를 나눠 씁니다. 테스트 키에는 키당 분당 15회라는 더 낮은 상한이 따로 있지만, 이 역시 같은 계정 윈도에 합산됩니다.

모든 응답에는 표준 헤더가 실려 있어 추측 없이 요청 속도를 조절할 수 있습니다. 헤더는 제한에 가장 가까운 윈도 기준으로 값을 알려줍니다:

응답 헤더

x-ratelimit-limit-requests: 60
x-ratelimit-remaining-requests: 58
x-ratelimit-reset-requests: 43

x-ratelimit-reset-requests는 단위 접미사가 없는 순수 정수로, 윈도에 빈 자리가 생길 때까지 남은 초를 나타냅니다. 기간 문자열이 아니라 숫자로 파싱하세요.

동시 요청

계정당 동시에 진행 중인 요청은 최대 8개입니다. 9번째 동시 요청은 429와 코드 too_many_concurrent_requests로 즉시 거부되며, 응답에는 retry-after: 1이 실립니다. 거부된 요청에는 아무것도 과금되지 않습니다. 스트리밍 호출은 스트림이 끝날 때까지 자리를 차지하므로, 보통 긴 스트림 때문에 상한에 닿게 됩니다.

json · 429

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_concurrent_requests",
    "message": "Too many concurrent requests for this account (limit 8)."
  }
}

두 상한은 일반 계정에서 고정이며 선불 잔액에 따라 늘어나지 않습니다. 더 큰 여유가 필요하다면 엔터프라이즈에서 상한을 올려 드립니다.