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

API-सक्षम मौजूदा खाते के लिए आपको तीन चीज़ें चाहिए:

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. मॉडल: 16 समर्थित मॉडल में से एक - उदाहरण के लिए। gpt-5.4-mini या claude-sonnet-5

Authentication

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

Endpoints

स्थिर सार्वजनिक सतह नीचे और मशीन-पठनीय OpenAPI 3.1 दस्तावेज़ में दी गई है। यहाँ सूचीबद्ध न किए गए फ़ील्ड upstream को भेजे जा सकते हैं, लेकिन वे स्वतः SUB&SUB के संगतता अनुबंध का हिस्सा नहीं बनते।

POST /v1/chat/completions

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

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-* 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 भी काम करता है)।

चलाने योग्य 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 फ़ॉर्मैट वाले prompt के token गिनें। वही x-api-key, anthropic-version, model, system, messages और tools फ़ील्ड उपयोग करें जो /v1/messages को भेजते हैं। इस endpoint का शुल्क नहीं लगता। :online suffix हटा दिया जाता है, लेकिन search results न तो लाए जाते हैं और न गिने जाते हैं।

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 सत्यापित सार्वजनिक आईडी लौटाता है - वही श्वेतसूची जो 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-compatible होने का अर्थ यह नहीं है कि हर upstream model का हर फ़ील्ड हर route पर सुनिश्चित है। सहायता के तीन स्तर हैं:

उपलब्ध models

दो अपस्ट्रीम परिवार। 7 OpenAI मॉडल साझा ChatGPT-स्तरीय खातों तक जाते हैं; 9 Claude मॉडल आधिकारिक Anthropic खातों द्वारा परोसे जाते हैं। प्रति-टोकन दरें स्तर पर निर्भर करती हैं (देखें मूल्य निर्धारण) - दोनों के लिए एक ही कुंजी काम करती है।

OpenAI

Anthropic

Reasoning effort

उपरोक्त प्रत्येक OpenAI मॉडल एक तर्क मॉडल है - बैकएंड दृश्यमान आउटपुट उत्सर्जित करने से पहले अधिक या कम "सोच" टोकन खर्च कर सकता है। बजट को नियंत्रित करने के लिए OpenAI /v1/chat/completions अनुरोध निकाय (या /v1/responses पर reasoning: {"effort": ...}) पर reasoning_effort सेट करें। Claude के लिए, Anthropic-मूल thinking और output_config.effort फ़ील्ड का उपयोग करें - /v1/messages अनुभाग देखें। OpenAI मॉडल समान पाँच प्रयास मान स्वीकार करते हैं:

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

चलाने योग्य Python streaming उदाहरण:

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)

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 वाले ही हैं:

पुनः प्रयास और विश्वसनीयता

सीमित retries रखें। Relay साझा upstream क्षमता पर चलता है और generation requests idempotent नहीं हैं।

• पुनः प्रयास करें: 429, 502, 503 और स्पष्ट रूप से अस्थायी 500 responses। retry-after मानें; न होने पर jitter के साथ exponential backoff उपयोग करें (जैसे 1 s, 2 s, 4 s; अधिकतम तीन प्रयास)।
• बिना बदलाव पुनः प्रयास न करें: 400, 401, 402 या 403। पहले payload, key, balance या access state ठीक करें।
• Duplicate का जोखिम: हर सफल generation attempt एक अलग billable request है। SUB&SUB अभी idempotency key से generation POST को deduplicate नहीं करता; application-level operation ID रखें और पूरा response मिलने के बाद retry न करें।
• Streaming: बाधित SSE stream फिर से शुरू नहीं किया जा सकता। Reconnect करने पर नई generation शुरू होगी और दूसरा शुल्क लग सकता है।

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 देखें।

Fable और अल्ट्रा दरें Anthropic की प्रकाशित सूची कीमतों से मेल खाती हैं। Sonnet 5 31 अगस्त, 2026 तक Anthropic की प्रारंभिक $2/$10 दर का उपयोग करता है; उस तिथि के बाद इसका प्रकाशित मानक मूल्य $3/$15 है। पूलित सदस्यता समर्थन के कारण अन्य स्तर अपस्ट्रीम दरों से नीचे चलते हैं।

रीज़निंग टोकन (जब आप OpenAI पर reasoning_effort सेट करते हैं, या Claude पर Anthropic का मूल thinking फ़ील्ड सेट करते हैं) मॉडल की स्तरीय दर पर आउटपुट टोकन के रूप में गिना जाता है - उच्च प्रयास के लिए कोई अलग अधिभार नहीं है, लेकिन एक गहरी सोच वाला अनुरोध आसानी से 10-50× अधिक आउटपुट टोकन उत्सर्जित कर सकता है कोई प्रयास नहीं, इसलिए डॉलर का बिल इसके साथ बढ़ता है।

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 tokens हर request के billing 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 नहीं हैं। Shared upstream capacity और provider-side throttling लागू रहते हैं; अगर आप उनसे टकराते हैं, तो relay एक retry-after header के साथ 429 लौटाता है। Per-key RPM / TPM limits की योजना है।

स्थिति और सहायता

• Sign-in किए हुए API-सक्षम खाते Console → Service Status में live provider health और System Notice में संचालन संबंधी घोषणाएँ देख सकते हैं।
• खाते, billing, privacy या security सहायता के लिए [email protected] पर ईमेल करें।
• API विफलता की रिपोर्ट में UTC timestamp, endpoint, model, HTTP status और API key का दिखाई देने वाला prefix दें। Support द्वारा redacted reproduction स्पष्ट रूप से माँगे बिना पूरी API key या prompt content कभी न भेजें।
• सेवा best-effort है और कोई SLA नहीं है। उपलब्धता व refunds के लिए केवल अंग्रेज़ी में उपलब्ध Terms of Service, और data handling के लिए Privacy Policy देखें।

दस्तावेज़ की अंतिम समीक्षा: 14 जुलाई 2026।