OpenAI-CompatibleとAnthropic-Compatible API：選び方

API-Compatibleが実際に意味すること

Compatible APIは、既知のrequest shapeを受け取り、既存のSDKやclientがparseできるresponseを返します。一般的なintegrationでは、application codeの大部分を残しながらBase URL、API Key、Model IDを変更します。

ただし、この表現には明確な境界があります。Providerがbasic text generationをサポートしていても、特定のparameter、hosted tool、audio、image endpoint、正確なerror semanticsには対応していない場合があります。同じmodel fieldを公開する2つのendpointでも、modelの一覧やaccessの付与方法が異なることがあります。

選択したprotocolを実際のrequestで確認しますか？ 自分のBetterTokenアカウントとAPI Keyを作成し、quickstartを開いてminimal testを1件送信できます。BetterTokenには、OpenAI-compatibleとAnthropic-compatibleの独立したinterfaceがあります。Protocol、Base URL、API Key type、現在のModel IDを最新のAPI referenceと一致させてください。

Requestと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、必須のoutput limit、protocol versionがあります。Anthropic公式APIでは、x-api-keyやanthropic-versionなどのheaderが使われます。

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

Compatible gatewayでは別のauthentication schemeを採用している場合があります。実際にcallするendpointのドキュメントからheaderを取得してください。公式APIのexampleはprotocol formatを説明するものであり、providerのintegration guideを置き換えるものではありません。

System instructionを置く場所もcontractごとに異なります。Messagesの中に含めるprotocolもあれば、別fieldで送るprotocolもあります。機械的な変換は、context order、cache prefix、client behaviorを変える可能性があります。

Chat Completions、Responses、Messagesは別のcontract

OpenAI-compatibleという言葉だけでは、実装されているinterfaceを特定できません。Migration前に正確なcontractを記録します。

• Chat Completions: messages array、choices内のresponse、delta内のstreamed fragment。
• Responses API: input items、型付きoutput items、response lifecycleごとのevent。
• Anthropic Messages: messages、別のsystem field、content blocks、独自のstream event。

LibraryがResponsesを想定している場合、/chat/completionsだけを実装したendpointでは不十分です。Claude CodeがAnthropic Messagesを要求する場合、OpenAI-compatible endpointはadapterなしでは動作しません。Base URLの置換だけで済むのは、clientとserverが同じcontractを実装している場合だけです。

Streamingとcompletionの違い

3つのinterfaceはいずれもdataをstreamできますが、event名と順序が異なります。

Responses APIは、response creation、output text fragment、terminal stateを型付きServer-Sent Eventsとして送ります。Clientはcompletion eventまで待つか、failedまたはincomplete responseを処理する必要があります。

Anthropic Messagesはmessage_start、content-block event、message_delta、message_stopを送ります。最初のHTTP responseが成功した後でも、開いているstream内にerrorが届くことがあります。

Chat Completionsでは、clientは通常choices[0].deltaを蓄積し、そのendpoint contractに従って終了を検出します。1つのmarkerだけを待つcodeを、確認せずResponsesやMessagesへ転用してはいけません。

Minimal handlerは4つのstateを保持します。

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

disconnectedはcompletedではありません。Partial responseの後でconnectionが終了した場合は、受信済みeventを保存し、retryがsafeか判断してください。

Tool useとstructured output

toolsやtool_callsのような似たfield名は、実際以上のcompatibilityを連想させます。少なくとも次をtestしてください。

• JSON Schemaと対応するtypeの制限。
• Parallel tool calls。
• Tool resultをmodelへ返す方法。
• Streamされたargumentの組み立て。
• Invalid JSONに対するbehavior。
• Strict structured outputとschema refusal。

Adapterはfield名を変えるだけでなく、callの意味を維持する必要があります。Side effectのあるtoolでは特に重要です。同じtool callを繰り返すと、messageを再送したり、別recordを作成したり、operationを2回実行したりする可能性があります。

ErrorをHTTP statusだけで対応付けない

401、403、404、429、5xxは最初の分類に役立ちますが、providerごとにerror bodyとheaderが異なります。次を保持してください。

• HTTP status。
• Provider error typeとcode。
• Secretを含まない短いmessage。
• Request ID。
• Retry関連header。
• Endpoint、protocol、Model ID。

API Key、完全なprompt、sensitive responseをlogに残さないでください。Gatewayがerrorをnormalizeする場合は、元のprovider codeを安全なinternal fieldへ保存します。そうしなければ、model not found、access不足、endpoint不一致がすべて役に立たない400へまとめられる可能性があります。

Protocolの選び方

既製のAI tool

最初にtoolのドキュメントを読みます。OpenAI Base URLを求め、Chat CompletionsまたはResponsesを使う場合は、対応するOpenAI-compatible endpointを選びます。ANTHROPIC_BASE_URLを読み、Messagesを想定する場合はAnthropic-compatible endpointを使います。

Model名からprotocolを選んではいけません。Gatewayでmodelを利用できても、clientは特定のrequest formatを必要とします。

自分のapplication

すでに使っているSDKと機能によって選択が変わります。新しいapplicationでは、必要なcapabilityを列挙してください。Streaming、tools、structured output、vision、token usage、batch operation、その他のendpointです。各項目をproviderの公式ドキュメントで確認します。

Provider migration

変更行数ではなくcontractのsurfaceを見積もります。Basic chatなら新しいconfiguration valueが3つだけで済む場合があります。Tools、long history、cache、streamingを使うagent applicationには、通常adapterとintegration testが必要です。

Production trafficを移す前にtestする

1. SDK、endpoint、API versionを記録する。
2. Current catalogから正確なModel IDをコピーする。
3. Toolsとstreamingを使わず、短いrequestを送る。
4. Basic responseをterminal eventまでstreamする。
5. External side effectのないsafe tool callを実行する。
6. 意図的にinvalidなModel IDでcontrolled errorを発生させる。
7. usage、status、request IDをDashboardと照合する。
8. Timeout処理とbounded retryをtestする。

ここまで確認してからreal trafficを移します。BetterTokenではAPI referenceから始め、protocolを1つ選び、agent toolsを有効にする前にminimal requestを確認してください。

FAQ

OpenAI-compatible APIはOpenAI APIを完全に再現しますか？

いいえ。この用語が示すのは、特定のinterfaceとのcompatibilityです。Model、parameter、tools、streaming、error、追加endpointは個別に確認する必要があります。

OpenAI SDKからAnthropic-compatible endpointをcallできますか？

SDKがOpenAI contractを送る場合、直接は利用できません。Anthropic Messagesをサポートするclient、またはmessages、streaming、tool useを正しく変換するadapterを使います。

Base URLを置き換えるだけで十分ですか？

すでにcompatibleなclientから短いtext requestを送る場合は、それだけで済むこともあります。Production migrationでは、Model ID、authentication、streaming、tools、errors、usageを必ず確認してください。

Claude Codeにはどのprotocolが必要ですか？

Claude Codeは通常、Anthropic-compatible interfaceを使います。正確なvariables、Base URL、model settingsは現在のBetterTokenガイドから取得してください。