API バージョニング
System One の意思決定 API のバージョニングと、TypeScript SDK が送るヘッダー。
System One のホスト型 HTTP API と、単体で動く TypeScript SDK は、バージョンの境界が別々です。このページでは、それぞれのバージョンが何を制御するか、既存のリクエストを見失わずにアップグレードする方法を説明します。クライアントの設定は SDK ガイドとホスト型クイックスタートを参照してください。
よくある質問
Q: System One API のバージョニングはどうNESS主宰ていますか？ A: System One は、ドキュメント化された互換スナップショット（と SDK の既定値）で、ホスト型意思決定 API の版を管理します。本番ではバージョンを固定し、アップグレード時はこのページに従ってください。
バージョンの 4 つの境界
| 境界 | 現在の挙動 |
|---|---|
| HTTP API のパス | 意思決定と抽出は POST /v1/systemone を使います（fields があるときは抽出）。モデルの発見は公開の GET /v1/models です。/v2 の意思決定エンドポイントや、リクエストヘッダーによるバージョンネゴシエーションはありません。 |
| 保守されている契約 | typesafe-2026-09-18 は、文書化されている互換スナップショットを示します。GET /api/system-one/config がこれを contract として返します。モデル ID ではなく、挙動を固定するヘッダーでもありません。 |
| SDK パッケージのバージョン | パッケージは独立してリリースされます。ホスト型の例は core@0.8.0、transport-fetch@0.8.0、adapter-system-one@0.7.0 を使います（いずれも core@^0.8.0 に解決されます）。パッケージの更新だけでは /v1 は変わりません。 |
| リクエストのモデル | 要求した ID、エイリアス、返された解決済み model は、HTTP と SDK のバージョンとは別物です。エイリアスは時間の経過で変わることがあります。 |
System One adapter には https://system-one.dev/v1 を明示してください。独立して保守されている公式の @typesafe-ai/sdk@0.6.0 は別のクライアントで、パス自体を付加するため、ベース URL は /v1 を含まない https://system-one.dev です。どちらも、このホスト型サービスに接続するときは System One のキーを使います。直接プロバイダ用の SDK adapter は独自のエンドポイントと資格情報を使い、そのプロバイダがホスト型のカタログにあることを意味しません。SDK クライアントと資格情報を参照してください。
バージョンヘッダーはありません
現在、バージョン交渉のためのヘッダーは存在しません。 TypeScript SDK がバージョンを固定するためのヘッダーを送ることもありません。判断材料になるのは、HTTP パス、コ管理工作されている契約文字列、SDK パッケージのバージョン、リクエストで指定するモデル ID です。バージョンを固定したい場合は、packages のバージョンを明示してインストールし、model を明示的に送ってください。
Requirement として公開されているのは、互換スナップショットの文字列だけです。モデル ID でも、挙動を固定するヘッダーでもありません。
現在のモデル情報を確認する
Playground のセレクターと Model information ボタン、またはモデル APIを使って、現在のモデル、単価、機能、上限を確認してください。ある時点のモデル一覧を、恒久的で完全な一覧として扱わないでください。モデルを選ぶも参照してください。
モデル ID やエイリアスは、不変なリリースや、独立した評価で同一の結果になることを保証しません。バージョン接尾辞を推測したり、SDK が対応する直接プロバイダのモデルがホスト型に存在すると仮定したりしないでください。固定バージョンが提供されている場合はそれを使い、要求した ID と返された model の両方を記録してください。固定バージョンでも、出力が決定的であるという保証ではありません。
モデルを変えると、リクエストの要件、回答、コストが変わることがあります。送信する前に現在の capabilities、limits、pricing を確認してください。特に、選択肢の最小数、質問名の規則、指示の必須可否、null と省略の違い、拡張フィールドの受け入れ可否はモデルごとに異なります。リクエスト契約が示すのは共有のサービス上限であり、すべてのモデルが最長のネイティブ HTTP スキーマを受け付けるという保証ではありません。既定値が変わることに頼らず、保存するリクエストには明示的なモデルを入れてください。
統合の更新
SDK パッケージを更新するときは、SDK ガイド、API のリクエストフィールド、SDK 移行ガイドを確認してください。旧 @system-one-ai/sdk@0.5.3 は非推奨です。現在の例では、core、adapter、transport のパッケージを分けて使います。インストールバージョンは明示的に保ち、本番のワークフローを切り替える前に、代表 questions で評価してください。パッケージの移行は公開 HTTP パスを変えず、adapter の契約差も消しません。
core 0.8 は ImageInput、任意のトップレベルの images、Clairic の extract({ state, fields }) を公開しています。systemOneAdapter@0.7.0 は extract リクエスト（画像を含む）をエンコードしますが、evaluate() の画像はエンコードしません。ホスト型の意思決定画像は Fetch／HTTPを使い、ホスト型の Clairic の画像は SDK の extract()を使います。機能は capabilities.inputs の image、limits.images、選択した limits.bytes で確認し、パッケージのバージョンから推測しないでください。
HTTP と SDK のレスポンス互換性
クライアントコードは、使用する回答フィールドを検証し、想定外のレスポンスフィールドを許容してください。任意のトークン数が欠落または null の場合は、不明のままであり 0 ではありません。warnings、rounding、会計用のフィールドを自分で合成しないでください。core SDK は、正規化された型付き結果を返します。ネイティブ Noul は Boolean として、トークン使用量は camelCase として表されます。ネイティブ HTTP と公式 TypeSafe クライアントは別の形を見せます。生のレスポンスヘッダーが必要���場合は Fetch か公式クライアントの withResponse() を使ってください。
クレジット、リクエスト ID、エラー分類、リプレイ状態は、文書化された HTTP ヘッダーから読みます。X-TypeSafe-Request-Id と公式クライアントの requestId は TypeSafe の追跡 ID、X-Request-Id は System One のリクエスト ID です。レスポンス契約とエラーリファレンスを参照してください。
非推奨の挙動
公開されている固定の非推奨通知期間、API の終息日、サポート SLA はありません。サービスは現在 Deprecation や Sunset ヘッダーを出力しておらず、それらの不在が互換性の無期限を保証するわけでもありません。自動アップグレード、古いモデルの恒久的な提供、すべてのモデル変更の通知は約束していません。計画された変更については support@system-one.devへ連絡してください。
既存の操作を先に完了させる
冪等性はアカウントと正規化リクエスト（実効の要求モデルを含む）にスコープされます。未解決の操作は、結果を復旧する間、同じキー、モデル、本文を保持しなければなりません。受け入れられた拡張フィールド、null と省略の違い、配列の順序、正確な小数値も比較に参加します。同じキーでモデル、ルーブリック、または意味のある入力を変えると 409 idempotency_conflict が返ります。
別のモデルは新しい操作であり、新しいキーが必要です。前の応答が遅いだけでモデルの置き換えや新しいキーの発行はしないでください。まず元の結果を確認してください。成功したリプレイは新しい評価も課金もせずに保存済みの結果を返し、元の System One のリクエスト ID を保ちます。
完了した操作のリプレイ保護はリクエスト作成から 24 時間です。その後は古いキーでも新しい課金対象の操作を開始でき、生涯の重複防止は保証されません。SDK のアップグレードをまたいで未解決の操作データを保持し、保留中のリクエストがあるクライアントを変更する前に冪等キーとリトライを確認してください。
内部リンク
API リファレンス、TypeScript SDK、API エラーコード、冪等キー（Idempotency key）を参照してください。