API Reference

SUB&SUB https://api.subnsub.com/v1 पर एक multi-provider relay expose करता है। OpenAI clients /v1/chat/completions पर hit करते हैं; Anthropic clients /v1/messages पर hit करते हैं। एक ही sk-cf-... key दोनों को route करती है — request body में model चुनें और relay upstream चुन लेता है।

Quick start

तीन चीज़ें जो आपको चाहिए:

1. Base URL: https://api.subnsub.com/v1 (OpenAI clients) या https://api.subnsub.com (Anthropic clients — SDK खुद /v1/messages append कर लेता है)
2. API key: console से जारी की गई sk-cf-...
3. Model: 21 verified models में से एक — जैसे gpt-5.4-mini या claude-haiku-4.5

Authentication

हर request में एक Authorization: Bearer sk-cf-... header होना ज़रूरी है। Keys console से जारी की जाती हैं और SHA-256 hashes के रूप में store होती हैं — creation screen छोड़ते ही plaintext हमेशा के लिए चला जाता है, इसलिए उसे तुरंत save करें।

Endpoints

POST /v1/chat/completions

एक chat completion request भेजें। Request का shape OpenAI Chat Completions API से मेल खाता है — OpenAI SDKs बिना बदलाव के काम करते हैं।

POST /v1/messages

claude-* models के लिए Anthropic-native endpoint — Anthropic SDK (anthropic-sdk-python, @anthropic-ai/sdk, claude-code) इस path के विरुद्ध बिना बदलाव के काम करता है। अपना base URL https://api.subnsub.com पर point करें और x-api-key header के ज़रिए authenticate करें (अगर आपका client पसंद करे तो Authorization-Bearer form भी काम करता है)।

GET /v1/models

वे models list करता है जिन्हें आप वास्तव में call कर सकते हैं। Relay sub2api से OpenAI और Anthropic catalogues को merge करता है और उन 21 models तक filter करता है जिन्हें हमने current account pool के विरुद्ध end-to-end-test किया है — phantom IDs जो routing time पर 503 देते हैं, या first token पर upstream-400 देते हैं, छिपा दिए जाते हैं। अगर हर configured upstream unreachable हो, तो endpoint एक भ्रामक खाली list के बजाय 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-4.5", "type": "model", ... },
    { "id": "claude-haiku-4.5",  "type": "model", ... },
    ...
  ]
}

उपलब्ध models

दो upstream families। 7 OpenAI models shared ChatGPT-tier accounts पर route होते हैं; 14 Claude models एक Kiro reverse proxy के ज़रिए AWS CodeWhisperer पर route होते हैं। Per-token rates tier पर निर्भर करते हैं (देखें Pricing) — एक ही key दोनों के लिए काम करती है।

OpenAI

Anthropic

Reasoning effort

ऊपर का हर OpenAI model एक reasoning model है — backend visible output emit करने से पहले अधिक या कम "thinking" tokens खर्च कर सकता है। Budget को control करने के लिए OpenAI /v1/chat/completions request body पर reasoning_effort set करें। Claude के लिए, Anthropic-native thinking request field का उपयोग करें (या कोई -thinking model variant चुनें) — देखें /v1/messages section। OpenAI models समान पाँच effort values स्वीकार करते हैं:

# 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": [ ... ]
}

Streaming

Server-Sent Events पाने के लिए "stream": true set करें। अंतिम chunk में एक usage block होता है (हम upstream stream_options.include_usage force करते हैं ताकि token counts हमेशा emit हों), फिर एक literal data: [DONE] stream को बंद कर देता है।

# 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]

Web search

endpoint द्वारा समर्थित किसी भी model ID में :online append करें और relay model को forward करने से पहले एक web search चलाएगा, results को conversation के आगे prepend करते हुए ताकि answer ताज़े data पर आधारित हो। यह suffix /v1/chat/completions और /v1/messages पर काम करता है (बाद वाले को फिर भी एक claude-* base चाहिए); कोई search-specific request fields ज़रूरी नहीं।

# 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?"}
    ]
  }'

यह कैसे काम करता है: relay :online हटाता है, सबसे हालिया user message को query के रूप में लेता है (400 characters पर capped), उपलब्ध होने पर extracted page text के साथ अधिकतम 3 results के लिए Tavily को call करता है, साथ ही एक optional Tavily-generated summary, फिर उन्हें request upstream भेजने से पहले उसी user turn के आगे एक स्पष्ट रूप से सीमांकित <search_results> block के रूप में prepend करता है। Search call का 8-second timeout होता है। Results जानबूझकर user role में inject किए जाते हैं — कभी system prompt में नहीं — ताकि untrusted snippets को system-priority instructions तक न बढ़ाया जा सके।

<search_results> block इस तरह दिखता है। इसके पहले एक one-line instruction होता है जो model को बताता है कि block को untrusted external data मानें और numbered items को inline cite करें:

<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 का उपयोग कब करें

Relay हर request पर एक ही Tavily call करता है और results inject करता है — यह कोई agentic search loop नहीं है। Model जो देखता है उसके आधार पर फिर से search करने का फ़ैसला नहीं करता, जैसा Perplexity Sonar या ChatGPT browse tool करते हैं। इस सीमा को ध्यान में रखकर योजना बनाएँ:

अंतिम user message को एक standalone search query के रूप में लिखें। Search आपके सबसे हालिया user turn के literal text के विरुद्ध चलती है (400 chars पर capped), इसलिए "और नवीनतम version के बारे में क्या?" जैसे conversational follow-ups बिना context के बेकार queries बन जाते हैं। Multi-turn chat में, जब आप :online जोड़ें तो topic को दोबारा बताएँ — जैसे "the latest one" के बजाय "latest version of the Anthropic Python SDK"।

जिन सवालों में multi-step synthesis चाहिए (compare-and-contrast, deep research), उन्हें कई turns में बाँटें और हर एक में :online जोड़ें। Model हर turn के ताज़े results पढ़ेगा; आप अगली query को manually steer करते हैं। ध्यान दें कि inject किया गया <search_results> block केवल upstream भेजा जाता है — यह आपके client को वापस echo नहीं होता और अगली request में preserve नहीं होता, इसलिए अगर कोई बाद वाला turn पहले के sources के विवरणों पर निर्भर हो, तो model से कहें कि वह उन्हें अपने visible reply में summarise करे। One-shot research mode समर्थित नहीं है।

Errors

Envelope इस पर निर्भर करता है कि आपने कौन-सा endpoint call किया — relay errors को उस protocol में लौटाता है जो caller के SDK से मेल खाता है, और upstream errors ज्यों के त्यों pass through किए जाते हैं।

OpenAI paths (/v1/chat/completions, /v1/responses, /v1/models) — OpenAI envelope:

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

Anthropic paths (/v1/messages, /v1/messages/count_tokens) — Anthropic envelope:

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

Anthropic envelope एक अलग shape का उपयोग करता है — कोई code field नहीं, और discriminator type: "error" top level पर होता है (inner error.type category देता है, जैसे authentication_error, invalid_request_error, permission_error, api_error)। Anthropic SDKs पहले से इस shape को parse करते हैं; सादे OpenAI SDK error handlers नहीं करते, इसलिए /v1/messages को किसी Anthropic SDK के साथ call करें (या raw HTTP करें)।

Status codes दोनों protocols में canonical HTTP वाले ही हैं:

Pricing और billing

Pay-as-you-go, microdollars में per token bill होता है (1 micro = $0.000001 = एक cent का 1/10,000) ताकि sub-cent requests सटीक रूप से track हों। Rates per 1M tokens हैं, tier के अनुसार — कौन-सा model किस tier पर map होता है, इसके लिए model table देखें।

Ultra-tier rates Anthropic के published Opus list price से मेल खाते हैं — सीधा pass-through, कोई margin नहीं। बाक़ी tiers pooled subscription backing की बदौलत अपने upstream rates से नीचे चलते हैं।

Reasoning tokens (जब आप OpenAI पर reasoning_effort set करते हैं, या किसी Claude -thinking variant का उपयोग करते हैं) model के tier rate पर output tokens के रूप में गिने जाते हैं — high effort के लिए कोई अलग surcharge नहीं है, लेकिन एक deep-thinking request आसानी से no-effort वाली request से 10–50× अधिक output tokens emit कर सकती है, इसलिए dollar bill उसी के साथ scale होता है।

Anthropic prompt-caching एक अलग line item के रूप में bill होती है: cache writes tier के input rate के 1.25× पर और cache reads 0.10× पर। तो एक haiku-4.5 cache hit की लागत 0.20 × 0.10 = $0.02 per 1M tokens होती है, और एक sonnet-4.5 cache hit की लागत 0.75 × 0.10 = $0.075 per 1M tokens होती है। Cache columns हर settle row पर record होते हैं ताकि console breakdown दिखा सके।

Balance real time में काटा जाता है जैसे ही हर request लौटती है — streaming requests के लिए, settlement [DONE] chunk आने के बाद चलता है। अपना live balance और per-request settlements /console#billing पर देखें।

Rate limits

आज कोई per-key rate limits नहीं हैं। Upstream account pool concurrency & OpenAI server-side throttling लागू होते हैं; अगर आप उनसे टकराते हैं, तो relay एक retry-after header के साथ 429 लौटाता है। Per-key RPM / TPM limits post-MVP आएँगी।