API 레퍼런스

SUB&SUB는 https://api.subnsub.com/v1에서 멀티 프로바이더 릴레이를 제공합니다. OpenAI 클라이언트는 /v1/chat/completions를, Anthropic 클라이언트는 /v1/messages를 호출합니다. 동일한 sk-cf-... 키가 양쪽 모두를 라우팅합니다 — 요청 본문에서 모델을 선택하면 릴레이가 업스트림을 선택합니다.

서비스 이용 가능 범위

빠른 시작

API가 활성화된 기존 계정에는 다음 세 가지가 필요합니다:

1. Base URL: https://api.subnsub.com/v1 (OpenAI 클라이언트) 또는 https://api.subnsub.com (Anthropic 클라이언트 — SDK가 직접 /v1/messages를 덧붙입니다)
2. API 키: 콘솔에서 발급된 sk-cf-...
3. 모델: 16 지원 모델 중 하나 — 예: gpt-5.4-mini 또는 claude-sonnet-5

인증

모든 요청에는 Authorization: Bearer sk-cf-... 헤더가 포함되어야 합니다. 키는 콘솔에서 발급되며 SHA-256 해시로 저장됩니다 — 생성 화면을 벗어나면 평문은 영구히 사라지므로 즉시 저장하세요.

엔드포인트

안정적인 공개 인터페이스는 아래 내용과 기계 판독 가능한 OpenAPI 3.1 문서에 설명되어 있습니다. 여기에 없는 필드는 upstream으로 전달될 수 있지만 SUB&SUB의 호환성 보장에 자동으로 포함되지는 않습니다.

POST /v1/chat/completions

채팅 완성 요청을 보냅니다. 요청 형식은 OpenAI Chat Completions API와 동일합니다 — OpenAI SDK가 수정 없이 작동합니다.

POST /v1/responses

OpenAI Responses API — 최신 OpenAI 요청 형태(client.responses.create(...)). 기본적으로 gpt-*, 채팅/완료와 동일한 호환성 브리지를 통해 claude-*의 모든 카탈로그 모델과 함께 작동합니다. 사용량은 동일하게 측정됩니다. 즉, 모델의 계층 비율에 따른 입력/출력 토큰입니다.

실행 가능한 Responses 예시:

curl https://api.subnsub.com/v1/responses \
  -H "Authorization: Bearer sk-cf-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "Explain exponential backoff in two sentences."
  }'

POST /v1/messages

claude-* 모델을 위한 Anthropic 네이티브 엔드포인트입니다 — Anthropic SDK(anthropic-sdk-python, @anthropic-ai/sdk, claude-code)가 이 경로에 대해 수정 없이 작동합니다. base URL을 https://api.subnsub.com로 지정하고 x-api-key 헤더로 인증하세요(클라이언트가 선호한다면 Authorization-Bearer 방식도 작동합니다).

실행 가능한 Anthropic Messages 예시:

curl https://api.subnsub.com/v1/messages \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

POST /v1/messages/count_tokens

전송 전에 Anthropic 형식 프롬프트의 토큰을 계산합니다. /v1/messages에 보낼 때와 동일한 x-api-key, anthropic-version, model, system, messages, tools 필드를 사용하세요. 이 엔드포인트는 과금되지 않습니다. :online 접미사는 제거되지만 검색 결과를 가져오거나 계산하지 않습니다.

curl https://api.subnsub.com/v1/messages/count_tokens \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Count this prompt."}]
  }'

GET /v1/models

실제로 사용할 수 있는 모델을 나열해 보세요. 릴레이는 업스트림 제품군 모두 상태를 확인하고 16개의 확인된 공개 ID를 반환합니다. 이는 POST 엔드포인트가 적용하는 것과 동일한 화이트리스트이므로 검색에서는 400하는 모델을 광고하지 않습니다. 업스트림 카탈로그에 연결할 수 없는 경우 엔드포인트는 오해의 소지가 있는 빈 목록 대신 502 models_unreachable을 반환합니다.

# sample response (truncated)
{
  "object": "list",
  "data": [
    { "id": "gpt-5.4-mini",      "type": "model", ... },
    { "id": "gpt-5.4",           "type": "model", ... },
    { "id": "claude-sonnet-5",     "type": "model", ... },
    { "id": "claude-fable-5",      "type": "model", ... },
    ...
  ]
}

호환성 범위

OpenAI 호환이 모든 upstream 모델의 모든 필드를 모든 경로에서 보장한다는 뜻은 아닙니다. 지원 범위는 다음 세 단계입니다:

사용 가능한 모델

두 개의 상류 가족. 7 OpenAI 모델은 공유 ChatGPT 계층 계정으로 라우팅됩니다. 9 Claude 모델은 공식 Anthropic 계정에서 제공됩니다. 토큰당 요율은 등급에 따라 다릅니다(가격 참조). 두 가지 모두에 동일한 키가 적용됩니다.

OpenAI

Anthropic

추론 강도

위의 모든 OpenAI 모델은 추론 모델입니다. 즉, 백엔드는 시각적 출력을 방출하기 전에 더 많거나 더 적은 "생각" 토큰을 소비할 수 있습니다. 예산을 제어하려면 OpenAI /v1/chat/completions 요청 본문에 reasoning_effort(또는 /v1/responses에 reasoning: {"effort": ...})을 설정하세요. Claude의 경우 Anthropic 기본 thinking 및 output_config.effort 필드를 사용합니다. /v1/messages 섹션을 참조하세요. OpenAI 모델은 동일한 5가지 노력 값을 허용합니다.

# Two equivalent forms — pick whichever your SDK supports
{
  "model": "gpt-5.4-mini",
  "reasoning_effort": "high",
  "messages": [ ... ]
}

{
  "model": "gpt-5.5",
  "reasoning": { "effort": "xhigh" },
  "messages": [ ... ]
}

스트리밍

Server-Sent Events를 받으려면 "stream": true로 설정하세요. 마지막 청크는 usage 블록을 담고(업스트림에 stream_options.include_usage를 강제하므로 토큰 수가 항상 방출됩니다), 그다음 리터럴 data: [DONE]이 스트림을 닫습니다.

# Streaming format (line by line)
data: {"id":"resp_...","choices":[{"delta":{"content":"Hi"}}]}

data: {"id":"resp_...","choices":[{"delta":{"content":"!"}}]}

data: {"id":"resp_...","choices":[],"usage":{"prompt_tokens":18,"completion_tokens":11,"total_tokens":29}}

data: [DONE]

실행 가능한 Python 스트리밍 예시:

from openai import OpenAI

client = OpenAI(
    api_key="sk-cf-xxxxxxxxxxxx",
    base_url="https://api.subnsub.com/v1",
)

stream = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    text = chunk.choices[0].delta.content if chunk.choices else None
    if text:
        print(text, end="", flush=True)

웹 검색

엔드포인트가 지원하는 모든 모델 ID에 :online을 덧붙이면 릴레이가 모델로 전달하기 전에 웹 검색을 실행하고, 그 결과를 대화 앞에 추가해 답변이 최신 데이터에 근거하도록 합니다. 이 접미사는 /v1/chat/completions와 /v1/messages에서 작동합니다(후자는 여전히 claude-* 베이스가 필요합니다). 검색 전용 요청 필드는 필요하지 않습니다.

# Same call as before — just :online on the model
curl https://api.subnsub.com/v1/chat/completions \
  -H "Authorization: Bearer sk-cf-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini:online",
    "messages": [
      {"role": "user", "content": "What did Anthropic ship this week?"}
    ]
  }'

작동 방식: 릴레이는 :online을 제거하고, 가장 최근 사용자 메시지를 쿼리로 삼아(400자로 제한) Tavily를 호출해 가능하면 추출된 페이지 텍스트와 함께 최대 3개의 결과를, 그리고 선택적으로 Tavily가 생성한 요약을 받은 다음, 요청을 업스트림으로 보내기 전에 명확히 구분된 <search_results> 블록으로 그 동일한 사용자 턴 앞에 추가합니다. 검색 호출에는 8초 타임아웃이 있습니다. 결과는 의도적으로 user 역할에 주입되며 — 시스템 프롬프트에는 절대 주입되지 않습니다 — 따라서 신뢰할 수 없는 조각이 시스템 우선순위 지시로 격상될 수 없습니다.

<search_results> 블록은 다음과 같이 보입니다. 그 앞에는 모델에게 이 블록을 신뢰할 수 없는 외부 데이터로 취급하고 번호가 매겨진 항목을 인라인으로 인용하라고 알리는 한 줄짜리 지시가 붙습니다:

<search_results query="What did Anthropic ship this week?" retrieved="2026-05-21">
Summary: <short LLM-generated synthesis of the result set>

[1] Anthropic launches Opus 4.8
URL: https://www.anthropic.com/news/opus-4-8
<extracted page text, or short snippet if extraction failed — up to ~2000 chars>

[2] ...
</search_results>

:online을 사용할 시점

릴레이는 요청당 한 번의 Tavily 호출을 하고 결과를 주입합니다 — 에이전트형 검색 루프가 아닙니다. 모델은 Perplexity Sonar나 ChatGPT 브라우즈 도구처럼 본 내용에 따라 재검색을 결정하지 않습니다. 이 한계를 염두에 두고 계획하세요:

마지막 사용자 메시지를 독립적인 검색 쿼리로 작성하세요. 검색은 가장 최근 사용자 턴의 리터럴 텍스트(400자로 제한)에 대해 실행되므로, "그럼 최신 버전은?" 같은 대화형 후속 질문은 컨텍스트가 없는 쓸모없는 쿼리가 됩니다. 멀티턴 채팅에서 :online을 추가할 때는 주제를 다시 기술하세요 — 예: "the latest one"이 아니라 "latest version of the Anthropic Python SDK"처럼.

다단계 종합이 필요한 질문(비교·대조, 심층 리서치)은 여러 턴으로 나누고 각각에 :online을 추가하세요. 모델은 각 턴의 새로운 결과를 읽으며, 다음 쿼리는 직접 조정하면 됩니다. 주입된 <search_results> 블록은 업스트림으로만 전송된다는 점에 유의하세요 — 클라이언트로 다시 반향되지 않으며 다음 요청에 보존되지도 않으므로, 이후 턴이 이전 출처의 세부 정보에 의존한다면 모델에게 그것을 가시적인 응답에 요약하도록 요청하세요. 원샷 리서치 모드는 지원되지 않습니다.

오류

엔벨로프는 호출한 엔드포인트에 따라 달라집니다 — 릴레이는 호출자의 SDK에 맞는 프로토콜로 오류를 반환하며, 업스트림 오류는 그대로 전달됩니다.

OpenAI 경로(/v1/chat/completions, /v1/responses, /v1/models) — OpenAI 엔벨로프:

{ "error": { "message": "...", "type": "...", "code": "..." } }

Anthropic 경로(/v1/messages, /v1/messages/count_tokens) — Anthropic 엔벨로프:

{ "type": "error", "error": { "type": "...", "message": "..." } }

Anthropic 엔벨로프는 다른 형식을 사용합니다 — code 필드가 없고, 판별자 type: "error"가 최상위에 있습니다(내부 error.type이 카테고리를 제공, 예: authentication_error, invalid_request_error, permission_error, api_error). Anthropic SDK는 이미 이 형식을 파싱합니다; 일반 OpenAI SDK 오류 핸들러는 그렇지 않으므로 /v1/messages는 Anthropic SDK로 호출하세요(또는 raw HTTP를 사용하세요).

상태 코드는 두 프로토콜 모두에서 표준 HTTP 코드입니다:

재시도 및 안정성

재시도 횟수를 제한하세요. 릴레이는 공유 upstream 용량을 사용하며 생성 요청은 멱등적이지 않습니다.

• 재시도: 429, 502, 503 및 명백히 일시적인 500 응답. retry-after를 따르고, 없으면 jitter가 포함된 지수 백오프(예: 1초, 2초, 4초, 최대 3회)를 사용하세요.
• 변경 없이 재시도하지 않음: 400, 401, 402, 403. 먼저 payload, 키, 잔액 또는 액세스 상태를 수정하세요.
• 중복 위험: 성공한 생성 시도마다 별도의 과금 요청입니다. SUB&SUB는 현재 idempotency key로 생성 POST를 중복 제거하지 않습니다. 애플리케이션에서 작업 ID를 유지하고 완전한 응답 후에는 재시도하지 마세요.
• 스트리밍: 중단된 SSE 스트림은 재개할 수 없습니다. 다시 연결하면 새 생성이 시작되며 두 번째 요금이 발생할 수 있습니다.

요금 및 청구

종량제이며, 마이크로달러 단위로 토큰당 청구됩니다(1마이크로 = $0.000001 = 1센트의 1/10,000)므로 1센트 미만 요청도 정확히 추적됩니다. 단가는 티어별 1M 토큰 기준입니다 — 각 모델이 어느 티어에 매핑되는지는 모델 표를 참조하세요.

Fable 및 Ultra 요금은 Anthropic의 공시 정가와 일치합니다. Sonnet 5는 2026년 8월 31일까지 Anthropic의 신규 $2/$10 요율을 사용합니다. 해당 날짜 이후 게시된 표준 가격은 $3/$15입니다. 다른 계층은 풀링된 구독 지원 덕분에 업스트림 요금보다 낮게 실행됩니다.

추론 토큰(OpenAI에 reasoning_effort을 설정하거나 Claude에 Anthropic의 기본 thinking 필드를 설정하는 경우)은 모델 계층 요율에서 output 토큰으로 계산됩니다. 높은 노력에 대한 별도의 추가 요금은 없지만 심층적 사고 요청은 쉽게 10~50배 더 많은 출력 토큰을 생성할 수 있습니다. 노력이 필요하지 않으므로 달러 지폐도 이에 따라 확장됩니다.

Anthropic 프롬프트 캐싱은 별도 항목으로 청구됩니다: 캐시 쓰기는 티어 입력 단가의 1.25×, 캐시 읽기는 0.10×입니다. 따라서 haiku-4.5 캐시 적중 비용은 0.20 × 0.10 = $0.02 per 1M tokens, sonnet-4.5 캐시 적중 비용은 0.75 × 0.10 = $0.075 per 1M tokens입니다. 캐시 토큰은 요청별 청구 기록에 항목별로 기록되며, 콘솔에서 세부 내역을 확인할 수 있습니다.

잔액은 각 요청이 반환될 때 실시간으로 차감됩니다 — 스트리밍 요청의 경우 [DONE] 청크가 도착한 후 정산이 실행됩니다. 실시간 잔액과 요청별 정산은 /console#billing에서 확인하세요.

사용량 제한

현재 키별 레이트 리밋은 없습니다. 공유 업스트림 용량과 제공자 측 스로틀링이 계속 적용됩니다; 이에 걸리면 릴레이는 retry-after 헤더와 함께 429를 반환합니다. 키별 RPM / TPM 제한은 도입 예정입니다.

상태 및 지원

• 로그인한 API 활성 계정은 콘솔 → 서비스 상태에서 공급자 상태를, 시스템 공지에서 운영 안내를 확인할 수 있습니다.
• 계정, 결제, 개인정보 보호 또는 보안 지원은 [email protected]으로 문의하세요.
• API 오류 신고 시 UTC 시각, 엔드포인트, 모델, HTTP 상태 및 화면에 보이는 API 키 접두사를 포함하세요. 지원팀이 삭제 처리된 재현 예시를 명시적으로 요청하지 않는 한 전체 API 키나 프롬프트 내용을 보내지 마세요.
• 서비스는 최선 노력 방식으로 제공되며 SLA가 없습니다. 가용성과 환불은 영어로만 제공되는 서비스 약관을, 데이터 처리는 개인정보 처리방침을 확인하세요.

문서 최종 검토일: 2026년 7월 14일.