OpenAI-Compatible या Anthropic-Compatible API: क्या चुनें

API-Compatible का असली अर्थ

Compatible API एक परिचित request shape स्वीकार करती है और ऐसा response लौटाती है जिसे मौजूदा SDK या client parse कर सके। आम integration में developer application code का बड़ा हिस्सा बनाए रखते हुए Base URL, API Key और Model ID बदलता है।

इस term की स्पष्ट सीमा है। Provider basic text generation support कर सकता है, लेकिन कोई खास parameter, hosted tool, audio, image endpoint या exact error semantics नहीं। model field दिखाने वाले दो endpoints भी models की listing और access rules में अलग हो सकते हैं।

चुने गए protocol को real request से test करना चाहते हैं? आप अपना BetterToken account और API Key बना सकते हैं, quickstart खोलकर एक minimal test भेज सकते हैं। BetterToken अलग OpenAI-compatible और Anthropic-compatible interfaces देता है; protocol, Base URL, API Key type और current Model ID को current API reference से match करना चाहिए।

Requests और authentication कैसे अलग हैं

OpenAI-compatible flow में client आम तौर पर Chat Completions के लिए messages या Responses के लिए input बनाता है। Authentication अक्सर Bearer token से होती है:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Anthropic Messages की अपनी message structure, अलग system field, required output limit और protocol version होती है। Anthropic की official API x-api-key और anthropic-version जैसे headers इस्तेमाल करती है:

x-api-key: YOUR_API_KEY
anthropic-version: CURRENT_SUPPORTED_VERSION
Content-Type: application/json

Compatible gateway अलग authentication scheme स्वीकार कर सकता है। Headers उसी endpoint की documentation से लें जिसे आप call कर रहे हैं। Official API example protocol format समझाता है; वह provider की integration guide की जगह नहीं लेता।

System instruction की जगह भी contracts में अलग होती है। एक protocol इसे messages के बीच रख सकता है, जबकि दूसरा अलग field में भेजता है। Mechanical conversion context order, cache prefix या client behavior बदल सकती है।

Chat Completions, Responses और Messages अलग contracts हैं

OpenAI-compatible शब्द यह नहीं बताता कि कौन-सा interface implement किया गया है। Migration से पहले exact contract दर्ज करें:

• Chat Completions: messages array, choices के अंदर response और delta में streamed fragments।
• Responses API: input items, typed output items और response lifecycle के अलग events।
• Anthropic Messages: messages, अलग system field, content blocks और अपने stream events।

अगर library Responses चाहती है, तो केवल /chat/completions वाला endpoint पर्याप्त नहीं है। Claude Code को Anthropic Messages चाहिए तो OpenAI-compatible endpoint adapter के बिना काम नहीं करेगा। Base URL बदलना केवल तब पर्याप्त है जब client और server एक ही contract implement करते हों।

Streaming और completion कैसे अलग हैं

तीनों interfaces data stream कर सकते हैं, लेकिन event names और order अलग होते हैं।

Responses API, response creation, output text fragments और terminal states के लिए typed Server-Sent Events भेजती है। Client को completion event तक wait करना या failed/incomplete response handle करना चाहिए।

Anthropic Messages में message_start, content-block events, message_delta और message_stop आते हैं। Initial HTTP response सफल होने के बाद भी खुले stream के अंदर error आ सकती है।

Chat Completions में client आम तौर पर choices[0].delta जमा करता है और endpoint contract के अनुसार end detect करता है। केवल एक marker की प्रतीक्षा करने वाला code verification के बिना Responses या Messages में copy नहीं किया जा सकता।

Minimal handler चार states रखता है:

created -> receiving -> completed
                   \-> failed
                   \-> disconnected

disconnected, completed नहीं है। Partial response के बाद connection बंद हो जाए तो मिले हुए events सुरक्षित रखें और तय करें कि retry करना safe है या नहीं।

Tool use और structured output

tools और tool_calls जैसे मिलते-जुलते field names वास्तविक से अधिक compatibility का आभास दे सकते हैं। कम से कम ये बातें test करें:

• JSON Schema और supported type restrictions;
• parallel tool calls;
• tool result को model तक वापस भेजने का तरीका;
• streamed arguments को assemble करना;
• invalid JSON पर behavior;
• strict structured output और schema refusals।

Adapter को केवल fields rename नहीं करने चाहिए; call का अर्थ बनाए रखना चाहिए। Side effects वाले tools में यह खास तौर पर जरूरी है: वही tool call दोहराने से दूसरी message भेजी जा सकती है, दूसरा record बन सकता है या operation दो बार execute हो सकता है।

Errors को केवल HTTP status से map न करें

401, 403, 404, 429 और 5xx शुरुआती classification देते हैं, लेकिन providers के error bodies और headers अलग होते हैं। ये values सुरक्षित रखें:

• HTTP status;
• provider error type और code;
• secrets के बिना short message;
• request ID;
• retry-related headers;
• endpoint, protocol और Model ID।

API Key, पूरा prompt या sensitive response log न करें। Gateway errors normalize करे तो original provider code को सुरक्षित internal field में बचाएँ। वरना model not found, missing access और mismatched endpoint सभी एक अनुपयोगी 400 में बदल सकते हैं।

Protocol कैसे चुनें

Ready-made AI tool

पहले tool documentation पढ़ें। अगर वह OpenAI Base URL माँगता है और Chat Completions या Responses इस्तेमाल करता है, तो संबंधित OpenAI-compatible endpoint चुनें। अगर वह ANTHROPIC_BASE_URL पढ़ता है और Messages चाहता है, तो Anthropic-compatible endpoint इस्तेमाल करें।

Protocol को model name से न चुनें। Gateway पर model उपलब्ध हो सकता है, फिर भी client को एक specific request format चाहिए।

आपका अपना application

Decision आपके मौजूदा SDK और features पर निर्भर है। नए application के लिए required capabilities की list बनाएँ: streaming, tools, structured output, vision, token usage, batch operations या दूसरे endpoints। हर item को provider की official documentation में verify करें।

Provider migration

बदली गई lines की संख्या नहीं, contract का surface estimate करें। Basic chat में केवल तीन नई configuration values लग सकती हैं। Tools, long history, cache और streaming वाला agent application आम तौर पर adapter और integration tests चाहता है।

Production traffic move करने से पहले test करें

1. SDK, endpoint और API version record करें।
2. Current catalog से exact Model ID copy करें।
3. Tools या streaming के बिना short request भेजें।
4. Basic response को उसके terminal event तक stream करें।
5. बिना external side effect वाला safe tool call चलाएँ।
6. जानबूझकर invalid Model ID से controlled error trigger करें।
7. usage, status और request ID को Dashboard से match करें।
8. Timeout handling और bounded retry test करें।

इन checks के बाद ही real traffic move करें। BetterToken के साथ API reference से शुरू करें, एक protocol चुनें और agent tools enable करने से पहले minimal request confirm करें।

FAQ

क्या OpenAI-compatible API पूरी OpenAI API reproduce करती है?

नहीं। यह term किसी specific interface के साथ compatibility बताता है। Models, parameters, tools, streaming, errors और additional endpoints को अलग-अलग verify करना पड़ता है।

क्या OpenAI SDK से Anthropic-compatible endpoint call कर सकते हैं?

अगर SDK OpenAI contract भेजता है, तो सीधे नहीं। Anthropic Messages support करने वाला client या messages, streaming और tool use को सही तरह convert करने वाला adapter इस्तेमाल करें।

क्या केवल Base URL बदलना पर्याप्त है?

पहले से compatible client में short text request के लिए कभी-कभी पर्याप्त हो सकता है। Production migration में फिर भी Model ID, authentication, streaming, tools, errors और usage verify करें।

Claude Code को कौन-सा protocol चाहिए?

Claude Code आम तौर पर Anthropic-compatible interface इस्तेमाल करता है। Exact variables, Base URL और model settings current BetterToken guide से लें।