AI API入門：プロトコル、API Key、最初のリクエスト

AI APIへ接続する前に、クライアントが想定するcontractを確認してください。選択肢はOpenAI-compatibleまたはAnthropic-compatibleです。次にproviderが文書化したBase URLを使い、API Keyをsource codeの外へ保存し、短いリクエストを1件送信して、レスポンスとusage recordの両方を確認します。設定画面で保存に成功しただけでは、意図したendpointへリクエストが届いた証明にはなりません。

Vendor固有のweb subscriptionではなくAPI gatewayが必要なら、BetterToken AI APIの概要から始めてください。BetterTokenには、OpenAI-compatibleとAnthropic-compatibleの独立したinterfaceがあります。使用するのは自分のBetterTokenアカウントとAPI Keyであり、OpenAIまたはAnthropic Consoleのkeyではありません。

API access、web subscription、shared accountの違い

これらは別のproductです。

Access path	得られるもの	それだけでは意味しないもの
API access	自分のkeyで認証したHTTPリクエスト	Vendorのconsumer chat subscriptionへのアクセス
Web subscription	特定のproduct interfaceと、そのplanに含まれるlimits	移転可能なAPI balanceやthird-party API Key
Shared account	他人のlogin session	安全またはproductionに適したintegration

通常のdevelopmentでは、自分で管理できるアカウントとkeyを使ってください。購入したloginやshared loginを前提にintegrationを構築してはいけません。

1. クライアントに合わせてprotocolを選ぶ

Modelを選ぶ前に、クライアントまたはSDKのドキュメントを読みます。ToolがOpenAI SDK、Chat Completions、Responses API、またはOPENAI_BASE_URLのようなfieldを想定している場合はOpenAI-compatibleを選びます。Messages requestを作成し、ANTHROPIC_BASE_URLまたはx-api-keyを必要とする場合はAnthropic-compatibleを選びます。

Model名でprotocolは決まりません。クライアントが、endpointの受け付けるrequest contractを作成できる必要があります。

OpenAI-compatible providerでは、Base URLとChat Completions pathは次の形式になります。

Base URL: https://api.example.com/v1
Full path: https://api.example.com/v1/chat/completions

Anthropic-compatible providerでは、Base URLはhttps://api.example.com、完全なMessages pathはhttps://api.example.com/v1/messagesのようになります。これは形式であり設定値ではありません。実際の値は選択したproviderの文書からコピーしてください。

プロトコルと最初のリクエストの項目を確認しますか？ API 設定リファレンスを開く

2. Base URLとrequest pathを区別する

SDKやtoolは通常Base URLを受け取り、resource pathを自動で追加します。Direct HTTP callでは完全なpathが必要です。

OpenAI-compatible raw path: https://api.example.com/v1/chat/completions
Anthropic Messages raw path: https://api.example.com/v1/messages

Base URLだけを求めるfieldへ完全なrequest pathを貼り付けないでください。クライアントがresourceを二重に追加し、404を返す可能性があります。

3. API Keyをcodeの外に置く

最初のlocal testではenvironment variableを使い、production credentialは利用するplatformのsecret managerへ移します。

export API_KEY="your_api_key_here"
export MODEL_ID="your_current_model_id"
export OPENAI_BASE_URL="https://api.example.com/v1"
export ANTHROPIC_BASE_URL="https://api.example.com"

実際のkeyをsource code、.env.example、prompt、issue、screenshot、support messageへ書かないでください。Marketing nameから推測せず、providerのドキュメントまたはmodel catalogから現在の正確なModel IDをコピーします。

4. 最小のOpenAI-compatibleリクエストを送る

Streamingやtoolsを有効にする前に、短いtext-only requestを使います。

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [{"role": "user", "content": "Reply with API_OK"}],
    "max_tokens": 16
  }'

他人と共有するlogではcurl -vを使わないでください。Verbose outputにsensitive headerが含まれる場合があります。

5. 最小のAnthropic-compatibleリクエストを送る

Messages requestでは、authentication headerとbodyの形式が異なります。

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL_ID"'",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Reply with API_OK"}]
  }'

CURRENT_SUPPORTED_VERSIONはplaceholderです。テスト前にAPI referenceで現在サポートされるheaderを確認してください。

6. レスポンスとusage recordを確認する

最初のテストが完了したと言えるのは、次のsignalがすべて一致したときです。

• HTTP statusが成功を示す。
• レスポンスにexpected Model IDまたは文書化されたdisplay valueが含まれる。
• 選択したcontractがexpected contentとusage fieldを返す。
• providerのusageまたはbilling recordに、期待するstatusとchargeのrequestがある。

Model availability、Model ID、pricingは変わります。予算を計算する前に、選択したproviderの現在のcatalogとprice pageを確認してください。

7. Response layerごとにトラブルシューティングする

• 401: key、余分なspace、authentication methodを確認します。Bearerとx-api-keyは互換ではありません。
• 404: Base URLと完全なpathを比較し、/v1、/chat/completions、/messagesが重複していないか調べます。
• model not found: 現在の正確なModel IDをコピーし、選択したkey groupとprotocolで利用できることを確認します。
• TimeoutまたはTLS error: local proxy、firewall、DNS、certificateの状態とAPI responseを切り分けます。TLS verificationを恒久的に無効化してはいけません。

実用的な順序は、client contractの確認、keyをsecretとして保存、正しいBase URLの設定、短いrequestの送信、responseとusage recordの確認です。その後にstreaming、tools、long context、agent workflowを追加してください。

次のステップ：OpenAI-compatible API

自分の key と OpenAI-compatible route を使う practical setup については、OpenAI API ページを確認してください。これは BetterToken の compatible API であり、official OpenAI key ではありません。

https://api.example.com、https://api.example.com/v1、https://api.example.com/v1/messages、https://api.example.com/v1/chat/completions は URL 形式の例です。選択したプロバイダーの文書にある値を使用してください。