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

Flatkey API クイックスタート: router.flatkey.ai で最初の呼び出しを行う

Flatkey APIキーを作成し、OpenAI互換のベースURLを切り替え、最初のリクエストを送信してレスポンスを確認します。さらに、Usage と Logs を見て、安全なフォールバックルーティングを追加します。

Flatkey API クイックスタート: `router.flatkey.ai` 経由で最初の呼び出しを行う

すでに OpenAI SDK を使っているなら、Flatkey API への最初の呼び出しに最短で到達する方法はシンプルです。Flatkey キーを作成し、クライアントの接続先を https://router.flatkey.ai/v1 に設定し、1 回 chat-completions リクエストを送信して、コンソールで呼び出しを確認します。

このクイックスタートでは、その一連の流れを通して説明します。また、最初のモデルが動作したあとに、エラーを隠したり無制限のリトライチェーンを作成したりせずに、基本的なフォールバックシーケンスを追加する方法も示します。

完了する内容

このガイドを終えると、次の状態になります。

Flatkey アカウントと API キーがある。
Flatkey ルーターを使用する OpenAI 互換クライアントがある。
1 回の成功したリクエストと、読みやすいレスポンスがある。
使用量、コスト、リクエストのトラブルシューティング用のコンソール確認ポイントがある。
本番前にテストできる小さなフォールバックパターンがある。

このスモークテストのために、新しい SDK を前提にアプリケーションを作り直す必要はありません。Flatkey の公開ドキュメントでは https://router.flatkey.ai/v1 に OpenAI 互換エンドポイントが公開されているため、一般的な chat、tool、streaming、structured-output のワークフローは、使い慣れたクライアントの形のまま利用できます。

開始前に

必要なもの:

Flatkey アカウント。
sk-fk- で始まる Flatkey API キー。
SDK の例を使う場合は Python 3.9+ または Node.js 18+。
現在あなたのアカウントで利用可能なモデル名。

モデルカタログと利用可否は変更されることがあります。古いモデル名をそのまま本番環境にコピーするのではなく、最新のモデルカタログまたはコンソールを使用してください。

ステップ 1: Flatkey アカウントを作成する

Flatkey のサインアップフローを開き、アカウントを作成します。サインイン後、コンソールを使用して、アプリケーションが各リクエストで送信する認証情報を作成します。

コンソール参照

Console → API Keys に移動します。

このクイックスタート用のキーを作成し、すぐにコピーしてください。キーはパスワードと同じように扱ってください。クライアントサイドのコードに貼り付けない、Git にコミットしない、スクリーンショットに含めない、サポートメッセージで送信しないでください。

チーム環境では、開発者やサービスごとに別々のキーを作成してください。Flatkey のドキュメントでは、月間上限やオプションのモデル許可リストなど、キーごとの制御も説明されています。これらの制御により、1 つのテストを分離したり、1 つの認証情報をローテーションしたり、すべてのアプリケーションに影響を与えずに 1 つのワークロードを停止したりしやすくなります。

シェルでキーを設定します:

export FLATKEY_API_KEY="sk-fk-your-key-here"

.env ファイルを使用する場合は、バージョン管理の外に置いてください:

FLATKEY_API_KEY=sk-fk-your-key-here

ステップ 2: ベース URL を変更する

OpenAI 互換の Flatkey ベース URL は次のとおりです:

https://router.flatkey.ai/v1

これは、このクイックスタートで最も重要な設定変更です。API キーはリクエストを認証し、ベース URL はそれを別のプロバイダーのエンドポイントへ直接送るのではなく、Flatkey ルーター経由にします。

アプリケーションロジックを編集せずに変更できるよう、両方の値を環境設定に保持してください:

export OPENAI_API_KEY="$FLATKEY_API_KEY"
export OPENAI_BASE_URL="https://router.flatkey.ai/v1"

フレームワークで想定されている変数名を使用してください。一部のライブラリでは OPENAI_BASE_URL を読み取りますが、別のものではクライアント作成時に base_url または baseURL オプションが必要です。

ステップ 3: 最初のリクエストを送信する

まずは短く、決定論的なプロンプトを 1 つ使って始めます。目的は、ストリーミング、ツール、構造化出力、フォールバック動作を追加する前に、認証、接続性、モデルアクセス、レスポンスの解析を確認することです。

オプション A: cURL

現在の Flatkey カタログで利用可能なモデルに YOUR_CURRENT_MODEL を置き換えてください:

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CURRENT_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: flatkey quickstart connected"
      }
    ],
    "temperature": 0
  }'

オプション B: Python

OpenAI クライアントをインストールします:

pip install openai

quickstart.py を作成します:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="YOUR_CURRENT_MODEL",
    messages=[
        {
            "role": "user",
            "content": "Reply with exactly: flatkey quickstart connected",
        }
    ],
    temperature=0,
)

print(response.choices[0].message.content)
print(response.usage)

実行します:

python quickstart.py

オプション C: JavaScript

クライアントをインストールします:

npm install openai

quickstart.mjs を作成します:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_CURRENT_MODEL",
  messages: [
    {
      role: "user",
      content: "Reply with exactly: flatkey quickstart connected",
    },
  ],
  temperature: 0,
});

console.log(response.choices[0].message.content);
console.log(response.usage);

実行します:

node quickstart.mjs

ステップ 4: レスポンスを読む

標準的な chat-completions リクエストでは、次の 4 つのフィールドから始めます:

フィールド	示している内容	初回呼び出しでの確認事項
`id`	レスポンスの識別子	トラブルシューティング用に一時的に保存する
`model`	レスポンスに関連付けられたモデル	テストしたかったルートと一致していることを確認する
`choices[0].message.content`	アシスタントの出力	アプリケーションがテキストを抽出できることを確認する
`usage`	呼び出しとともに返されるトークン使用量	コストおよび回帰チェックのためにログを取る

簡略化したレスポンスは次のようになります:

{
  "id": "chatcmpl-example",
  "model": "YOUR_CURRENT_MODEL",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "flatkey quickstart connected"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 5,
    "total_tokens": 17
  }
}

正確な識別子とトークン数は異なります。最初の呼び出しの成功条件はバイト単位での一致ではなく、有効な HTTP レスポンス、解析可能なアシスタントメッセージ、そしてアプリケーションが記録できる使用量情報であることです。

Step 5: 呼び出し後に使用量を確認する

200 OK で止めないでください。有用なクイックスタートは、そのリクエストが統合を運用する担当者にも見えることを確認するところまで行います。

Console リファレンス

リクエストの後に Console → Usage & Logs を開いてください。

新しい呼び出しを探し、アカウントで確認できる詳細を次のような項目で確認します:

リクエスト時刻。
モデルまたはルート。
ステータス。
トークン使用量。
コストまたは残高への影響。
リクエストが失敗した場合のエラー詳細。

アプリケーションがレスポンスを受け取っているのに、期待したログエントリがない場合は、まずリクエストで使用したものと同じアカウント、ワークスペース、API キーを表示していることを確認してください。また、再試行する前にレスポンス ID とリクエスト時刻も記録してください。この 2 つの情報があると、トラブルシューティングがはるかに সহজになります。

スモークテストから継続的なワークロードに移る前に、現在の Flatkey の料金ページを確認してください。1 回の成功した呼び出しのコストだけでなく、使用する予定のモデル、リクエスト量、トークンの内訳、フォールバック動作を比較してください。

Step 6: 安全なフォールバックシーケンスを追加する

フォールバックルーティングは、最初のモデルが動作してから追加すべきです。そうしないと、バックアップルートが本当の問題、つまり無効なキー、誤ったベース URL、利用不可のモデル、形式の不正なリクエスト、またはアカウント制限を隠してしまう可能性があります。

同じ作業に対してテスト済みのモデルを、短い順序付きリストで始めてください:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

models = [
    "PRIMARY_CURRENT_MODEL",
    "FALLBACK_CURRENT_MODEL",
]

last_error = None

for model in models:
    try:
        response = client.chat.completions.create(
            model=model,
            messages=[
                {
                    "role": "user",
                    "content": "Return JSON with one key named status and value ok",
                }
            ],
            temperature=0,
        )
        print(model, response.choices[0].message.content)
        break
    except Exception as error:
        last_error = error
        print(f"Route failed: {model}")
else:
    raise RuntimeError("All approved model routes failed") from last_error

この例は意図的に小さくしています。本番で使用する前に、次を追加してください:

再試行可能なエラーの狭い一覧。
各試行ごとのタイムアウトと、リクエスト全体の期限。
一時的な失敗に対するバックオフ。
試行したモデルとレスポンス ID を含む構造化ログ。
JSON、ツール呼び出し、またはその他必須スキーマの出力検証。
フォールバックが不適切なルートを黙って選択しないようにするコスト上限。

認証エラーを複数のモデルで再試行しないでください。リクエストが修正されるまで、不正な形式のリクエストを再試行しないでください。chat-completions ペイロードを受け付けるからといって、すべてのモデルを同一視しないでください。

実践的なフォールバックポリシー

次の判定表を出発点として使用してください:

失敗	同じモデルを再試行?	承認済みフォールバックを試す?	アクション
ネットワークタイムアウト	1回、期限内で	はい	元のリクエスト ID を保持し、両方の試行をログに記録する
レート制限	バックオフ後	はい	再試行ガイダンスを尊重し、総遅延を上限で制御する
一時的なサーバーエラー	1回	はい	承認済みルート一覧を使い切ったら停止する
無効な API キー	いいえ	いいえ	認証情報をローテーションするか修正する
不明/利用不可のモデル	いいえ	はい	モデル選択を更新する。同じ名前でループしない
無効なリクエストスキーマ	いいえ	いいえ	ペイロードを修正して検証する
出力の検証失敗	場合による	はい	ワークフローで検証ルールが定義されている場合にのみ再試行する