AI コーディング

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

正しいAI API protocolを選び、keyを安全に保管して最小リクエストを送り、response、routing、usage recordを確認する手順です。

BetterToken

編集チーム

2026年8月5日2 分で読めます

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を作成できる必要があります。

BetterTokenのBase URLは次のとおりです。


OpenAI-compatible Base URL:  https://www.bettertoken.ai/v1
Anthropic-compatible Base URL: https://bettertoken.ai/

OpenAI-compatibleの値には/v1がすでに含まれています。Anthropic-compatibleの値には含まれず、raw Messages requestでは完全なresource pathとして/v1/messagesを使います。

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

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


OpenAI-compatible raw path:  https://www.bettertoken.ai/v1/chat/completions
Anthropic Messages raw path: https://www.bettertoken.ai/v1/messages

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

3. API Keyをcodeの外に置く

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


export BETTERTOKEN_API_KEY="your_api_key_here"
export BETTERTOKEN_MODEL_ID="your_current_model_id"

実際の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 https://www.bettertoken.ai/v1/chat/completions \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_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 https://www.bettertoken.ai/v1/messages \
  -H "x-api-key: $BETTERTOKEN_API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$BETTERTOKEN_MODEL_ID"'",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Reply with API_OK"}]
  }'

CURRENT_SUPPORTED_VERSIONはplaceholderです。テスト前にAPI referenceで現在サポートされるheaderを確認してください。Claude-compatible accessが目的なら、最小リクエストへ戻る前にClaude APIのsetupとaccess boundariesを確認します。

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

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

HTTP statusが成功を示す。
レスポンスにexpected Model IDまたは文書化されたdisplay valueが含まれる。
選択したcontractがexpected contentとusage fieldを返す。
BetterToken Workspaceに同時刻のrecordがあり、model、status、該当するinput/output/cache tokens、chargeが表示される。

Workspaceはusageとbillingの記録です。完全なpromptやresponse bodyが保存されるとは想定しないでください。Dynamicな一覧をintegration noteへコピーするのではなく、availabilityとpricingは現在のmodel catalogで確認します。

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

401または403: key、key group、whitespace、Base URL、選択したprotocolで必要なauthentication headerを確認します。
404: Base URLと完全なpathを比較し、/v1、/chat/completions、/messagesが重複していないか調べます。
model not found: 現在の正確なModel IDをコピーし、選択したkey groupとprotocolで利用できることを確認します。
429: response bodyを読み、指定されたretry delayを守ります。もう1件送る前に、現在のconcurrencyまたはrate limitsを確認してください。
TimeoutまたはTLS error: local proxy、firewall、DNS、certificateの状態とAPI responseを切り分けます。TLS verificationを恒久的に無効化してはいけません。
Workspace recordがない: 古いenvironment variableによって別providerへrouteされていないか確認します。

Configurationを変更したら、短いリクエストをもう1件送ってWorkspaceと照合します。成功後はstreaming、tools、longer context、agent loopを1層ずつ追加してください。そうすれば、新しいfailureごとのdiagnostic surfaceを小さく保てます。

次のステップ：OpenAI-compatible API

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

LLM ワークフローを最適化しませんか？

単一 API でモデルを接続し、キーと AI コストを管理できます。