Base URL and SDK Migration2026年7月24日Flatkey Team

複数のAIモデルで使うcURLによるChat Completions

1つのOpenAI互換cURLリクエストでGPT、Claude、Gemini、DeepSeekの各モデルファミリーをテストし、出力を比較し、安全な失敗処理を追加します。

AIゲートウェイについては、長い機能一覧を見るよりも、たった1つのターミナルコマンドから多くを学べます。ゲートウェイが本当にOpenAI互換であれば、サポートされているモデルファミリー間で同じcurlリクエストが機能し、ベースURL、認証ヘッダー、メッセージ形式、レスポンス解析は安定したままのはずです。

このチュートリアルでは、Flatkeyを使った実践的なパターンを紹介します。1つのchat-completionsリクエストから始め、モデル名を変数に移し、統合を書き直すことなく複数の現行モデルファミリーをテストします。SDKを追加したりアプリケーションコードをコミットしたりする前に、ターミナルからAPIを検証したい開発者向けに設計されています。

モデル選択に関する注記: モデルカタログは変更されます。以下のモデルIDは、2026年7月24日時点で確認したFlatkeyの公開ドキュメントを反映しています。本番でIDを使用する前に、現在のモデル行と利用可否を確認してください。

The shortest working chat-completions cURL request

FlatkeyのAPIキーを作成し、シェルでエクスポートして、OpenAI互換のchat-completionsエンドポイントにリクエストを送信します:

export FLATKEY_API_KEY="your-flatkey-api-key"

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Write a one-sentence product description for a waterproof daypack."
      }
    ]
  }'

重要なのは4つの要素です:

Request part	What stays stable
Base URL	`https://router.flatkey.ai/v1`
Endpoint	`/chat/completions`
Authentication	`Authorization: Bearer $FLATKEY_API_KEY`
Message shape	An array of role-and-content objects

互換性のあるchatモデルでは、切り替える主なフィールドはmodelです。

Use the same cURL shape across model families

リクエスト本文を変更しなくて済むように、モデルIDをシェル変数に入れます:

export FLATKEY_API_KEY="your-flatkey-api-key"
export MODEL="gpt-4o-mini"

curl -sS https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"Return concise ecommerce copy.\"
      },
      {
        \"role\": \"user\",
        \"content\": \"Write a product title for a lightweight waterproof daypack.\"
      }
    ],
    \"temperature\": 0.2
  }" | jq -r '.choices[0].message.content'

次に、別のドキュメント化されたモデルIDでコマンドを再実行します:

export MODEL="claude-sonnet-4-6"

export MODEL="gemini-2.5-flash"

export MODEL="deepseek-v3.1"

リクエストは引き続き同じエンドポイント、ヘッダー、メッセージ、およびjqパーサーを使用します。この安定した呼び出し形状が運用上の利点です。つまり、プロバイダーごとに別々のターミナルスクリプトを保守しなくても、対応モデルファミリーを比較できます。

モデル選択に関する注意: 共有されたリクエスト形状は、すべてのモデルが同一に動作することを意味するわけではありません。サポートされるパラメーター、コンテキスト制限、ツールの動作、安全性の挙動、レイテンシー、出力スタイルは異なる場合があります。互換性は統合を सरलにする入り口として扱い、モデル同士が入れ替え可能である証拠とは考えないでください。

小さなマルチモデルテストループを実行する

ターミナルで素早く比較するには、短いリストを定義して同じプロンプトを各モデルに送信します:

#!/usr/bin/env bash
set -euo pipefail

: "${FLATKEY_API_KEY:?最初にFLATKEY_API_KEYを設定してください}"

MODELS=(
  "gpt-4o-mini"
  "claude-sonnet-4-6"
  "gemini-2.5-flash"
  "deepseek-v3.1"
)

PROMPT="防水仕様の通勤用バックパック向けに、利点を強調した箇条書きを3つ書いてください。"

for MODEL in "${MODELS[@]}"; do
  echo
  echo "=== $MODEL ==="

  jq -n \
    --arg model "$MODEL" \
    --arg prompt "$PROMPT" \
    '{
      model: $model,
      messages: [
        {role: "system", content: "You write concise ecommerce copy."},
        {role: "user", content: $prompt}
      ],
      temperature: 0.2
    }' |
  curl -sS https://router.flatkey.ai/v1/chat/completions \
    -H "Authorization: Bearer $FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -r '.choices[0].message.content // .error.message'
done

jq -n を使って JSON を構築する方が、長いシェル文字列を手動でエスケープするより安全です。また、変数、追加メッセージ、オプションパラメーターを使ってスクリプトを拡張しやすくなります。

スクリプトを compare-models.sh として保存し、実行可能にしてから実行します:

chmod +x compare-models.sh
./compare-models.sh

出力で比較すべき点

マルチモデルのテストは、プロンプトと評価方法が一貫している場合にのみ有用です。eコマースのコピー作成タスクでは、次を比較します:

Dimension	Terminal-friendly check
Instruction following	出力はちょうど3つの箇条書きを返しましたか?
Format stability	応答は特別な例外処理なしでパースできますか?
Brand fit	トーンは具体的で信頼でき、根拠のない主張がありませんか?
Latency	リクエストにどれくらい時間がかかりましたか?
Token usage	応答は`usage`オブジェクトで何を報告しましたか?
Error behavior	失敗したリクエストは役立つエラーメッセージを返しますか?

レイテンシーが重要な場合は、cURL のタイミング項目を追加します:

curl -sS -o response.json \
  -w 'status=%{http_code} total=%{time_total}s\n' \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "5語の製品タグラインを書いてください。"}
    ]
  }'

jq . response.json

これにより、転送の計測とモデル出力が分離されます。端末にはHTTPステータスとリクエスト全体の所要時間が表示され、JSONレスポンスは確認用にそのまま保持されます。

モデル選定に関する注意: 1つのレスポンスだけで本番用モデルを選ばないでください。代表的なプロンプトセットを実行し、リクエストを繰り返し、アプリケーションにとって重要な要件に照らして出力を評価してください。

リクエストを比較可能に保つ

プロンプトやパラメータの小さな変更でも、モデルテストが誤解を招くものになることがあります。以下の制御を使ってください:

メッセージを同一に保つ。 あるモデルだけプロンプトを改善して、他はそのままにしないでください。
同じtemperatureを使う。 一般に低い値のほうが比較実行を確認しやすくなります。
生のJSONを保存する。 レンダリングされたテキストだけでなく、完全なレスポンスを保存してください。
モデルIDを記録する。 表示名だけでは再現可能なテストには十分正確ではありません。
エラーと不正解を分ける。 転送や可用性のエラーは、出力品質のスコアではありません。
現在の利用可否を確認する。 ドキュメントにあるモデルでも、運用状況は変化する可能性があります。

基本的な失敗時の処理を追加する

--fail-with-body を使うと、cURLはHTTPエラーで終了しつつレスポンス本文を保持できます:

HTTP_BODY=$(mktemp)

if ! curl --fail-with-body -sS \
  -o "$HTTP_BODY" \
  https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "readyという単語を返してください。"}
    ]
  }'; then
  jq -r '.error.message // "Request failed"' "$HTTP_BODY" >&2
  rm -f "$HTTP_BODY"
  exit 1
fi

jq -r '.choices[0].message.content' "$HTTP_BODY"
rm -f "$HTTP_BODY"

アプリケーションコードでは、明示的なタイムアウト、再試行可能な失敗に対する上限付きリトライ、秘密鍵や機微なプロンプト内容を露出しないログ記録も追加してください。

実用的なモデル選定ポリシー

最もシンプルなポリシーは、プロバイダー名ではなくワークロードで選ぶことです:

ワークロード	最初のテスト	本番展開前に確認すべきこと
高ボリュームのシンプルなコピー	高速でコスト効率の高いモデル	フォーマット準拠と許容可能なエラー率
ニュアンスのあるブランド文書作成	より強力な汎用モデル	トーン、事実面での慎重さ、修正率
長文コンテキストの要約・統合	適切なコンテキストサポートを持つモデル	検索品質と切り捨て時の挙動
低レイテンシが重要なUI	低レイテンシモデル	1回の高速応答だけでなく、テールレイテンシ
フォールバック経路	別ファミリーのモデル	パラメータ互換性と出力契約

品質しきい値を確実に満たす、最も小さいモデルから始めてください。タスクがそれを必要とするときに、より強力なモデルへ切り替えます。フォールバックルーティングを追加する場合は、アプリケーション変更なしに主モデルの置き換えが可能だと仮定するのではなく、同じレスポンス契約でフォールバックをテストしてください。

本番テスト用のIDを選ぶ前に、Flatkeyの価格ページで現在のモデルアクセスと価格を確認できます。

cURLからSDKへ移行するタイミング

cURLは、次の4点を素早く確認するのに最適です:

APIキーが機能する
ベースURLが正しい
選択したモデルがリクエストを受け付ける
レスポンス形式がパーサーと一致する

ストリーミング補助、構造化されたリトライロジック、型付きレスポンス、再利用可能なクライアント、アプリケーションレベルの可観測性が必要になったらSDKへ移行します。成功したcURLリクエストは運用手順書に残しておきましょう。ゲートウェイアクセスの問題とSDK設定の問題を切り分ける最速の方法であり続けます。