API リファレンス

System One は、HTTP で構造化された選択肢、スコア、yes/no の確率を提供します。このリファレンスでは、ホスト型意思決定 API のリクエスト形式、認証、レスポンスの契約、制限を説明します。TypeScript アプリケーションから使う場合は ホスト型 SDK クイックスタート から始めてください。単体で利用できる System One SDK も、それぞれ独自の adapter と資格情報を持つ統合経路です。

よくある質問

Q: System One API とは？ A: Choice、Score、Noul（yes-no）のためのホスト型意思決定 API です。API キーで認証し、エージェント向けの型付き意思決定を受け取ります。

Q: エラー・冪等性・バージョニングは？ A: /ja/docs/api/ の配下にある各ページを参照してください。

ベース URL と認証

API キーは System One のコンソールで作成します。統合ツールの秘密情報欄やサーバー上に保管し、ブラウザコード、共有ドキュメント、スクリーンショットには置かないでください。キーの管理と失効はコンソールで行います。リクエストにはアカウントのクレジットが使われます。

API のオリジンは本体のアプリケーションであり、ドキュメントのホストではありません。POST /v1/systemone は System One の Bearer キーを必要とし、意思決定の questions または抽出の fields を受け取ります。GET /v1/models は公開です。直接接続するプロバイダの API キーは System One のアカウントキーではありません。

以下の YOUR_API_KEY、YOUR_MODEL_ID、YOUR_OPERATION_KEY はプレースホルダーであり、実際の資格情報やモデル名ではありません。モデルのプレースホルダーはモデルを選ぶ手順に沿って置き換えてください。

GET /v1/models

現在のモデル一覧を取得します。このエンドポイントは公開で、呼び出し側の Bearer は無視され、401 にはなりません。

curl 'https://system-one.dev/v1/models' \
  -H 'Accept: application/json'

レスポンスは data 配列ではなく models 配列を持つオブジェクトです。件数や順序は固定されません。

現在の Playground セレクターと Model information ボタンで、可用性、価格、上限を確認してください。現在のモデルはすべてテキストと JSON に対応し、capabilities.inputs に image が含まれる項目と limits.images を持つ項目は画像も受け付けます。画像に対応しないモデルは、画像を含むリクエストを拒否します。モデル一覧は変わるため、固定のカタログをコードに埋め込まず、新しい項目を受け入れられるようにしてください。モデル一覧の取得は意思決定クレジットを消費せず、ハッシュ化 IP ごとに毎分 60 リクエストという別の上限があります。

ゲートウェイ上限

次の値はサービス全体の最大値です。選択したモデルの limits はより厳しいことがあります。サイズは 1024 基準です。64KB = 65,536 バイト、13MB = 13,631,488 バイト、4MB = 4,194,304 バイト、8MB = 8,388,608 バイト。

state、指示、質問 ID

選択した項目の limits.requiresInstructions、questionNameLength、questionNamePattern を使います。

• 指示を必須とするモデルでは、state は null にできません。各質問に空でない文字列、オブジェクト、配列の指示が必要です。ID は A–Z、a–z、0–9、_、.、- を使います。Score の criteria は null にできず、Noul の criteria は省略するか true／false だけのオブジェクトにします。追加の質問フィールドは使えません。
• その他のモデルでは、null の state と、省略または null の指示を許します。質問 ID は空にできません。

POST /v1/systemone

YOUR_MODEL_ID を置き換えて、この本文を request.json として保存します。

{
  "model": "YOUR_MODEL_ID",
  "state": { "message": "I was charged twice for one order." },
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Choose the reviewing team.",
      "criteria": { "billing": "Payments and refunds", "support": "Technical help" }
    },
    "urgency": {
      "type": "score",
      "instructions": "Evaluate urgency with the ordered rubric.",
      "criteria": ["Normal review", "Timely response", "Immediate human attention"]
    },
    "duplicate": {
      "type": "noul",
      "instructions": "Does the message report a duplicate charge?"
    }
  }
}

キーと UUID などの一意な操作キーを付けて送ります。操作キーとリクエストは送信前に保存し、同じ操作の復旧にだけ再利用します。

curl --include 'https://system-one.dev/v1/systemone' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_OPERATION_KEY' \
  --data-binary @request.json

置き換えたあとは、この例は実際に課金される可能性のあるリクエストです。レスポンスは通常の JSON であり、ストリームではありません。操作キーは任意ですが、無い場合は同じリクエストの再送が新しい評価になります。リトライを有効にする前に 冪等キーとリトライを読んでください。

Windows の PowerShell では curl.exe と PowerShell のクォート規則を使うか、SDK クイックスタートを使ってください。文書化されている互換スナップショットは typesafe-2026-09-18 です。モデル ID でもバージョン指定のヘッダーでもありません。

リクエストのフィールド

次の入力形式は、現在のモデル選択で共通して使えます。選択したモデルの上限は引き続き適用されます。

質問 ID は文字、数字、ドット、アンダースコア、ハイフンだけを使い、100 文字以内にしてください。オプション名は空でなく 128 文字以下です。他の名前を使う前に、選択したモデルの質問名の規則を確認してください。文書化されたフィールドだけを使い、null 値や追加フィールドがすべてのモデルでサポートされるとは限りません。

model を省略するとサービスの既定モデルが使われます。既定がない場合は、課金前にリクエストが 422 になります。明示的な値が優先されます。ホスト型の ID とエイリアスはカタログから得ます。検証に失敗しても、モデルは自動的に切り替わりません。

画像と Fetch

画像に対応したカタログ項目では、PNG（image/png）、JPEG（image/jpeg）、WebP（image/webp）を送れます。ゲートウェイの上限は 画像 4 枚、デコード後 1 枚 4MB、合計 8MB、完全な UTF-8 JSON で 13MB です。選択した項目の limits.bytes と limits.images はより厳しいことがあります。データ URL には実際の base64 バイトが含まれます。オブジェクト形式は { mediaType, base64 } で、プロバイダのワイヤ形式 content_type ではありません。モデル ID から対応可否を推測しないでください。リモート URL、サーバー側ダウンロード、音声、動画は使えません。

systemOneAdapter@0.7.0 は evaluate() の画像をエンコードしません。ホスト型の意思決定画像には通常の Fetch を使ってください。Clairic の画像は extract()を使います。

制限とコスト

選択したモデルはより厳しい上限を課せます。有効な UTF-8 JSON を、重複するオブジェクトキーなしで送ってください。アカウントのレート制限は API キーと Playground のリクエストで共有され、リプレイの試行も含みます。意思決定の既定上限は毎分 120 リクエストです。API 認証には IP ごとに毎分 600 試行という別のガードがあり、モデル発見にはアカウントごとに毎分 60 リクエストの上限があります。

クレジットの計算は次のとおりです。

credits = 質問数 × max(1, ceil(解析済みのリクエスト全体の UTF-8 バイト数 / モデルの pricing.bytesPerBlock)) × pricing.creditsPerBlock

課金は解析済みのリクエスト全体を基準にし、整形のための空白は加わりません。基礎となる requests とリクエストの絶対的身份（冪等性の比較）は別の計算です。操作を始める前に現在の pricing を確認してください。

結果の読み方

次のレスポンスは回答の形を示したものです。実際の出力ではありません。ACTUAL_MODEL_ID はサービスが返したモデル名を示します。

{
  "model": "ACTUAL_MODEL_ID",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.8, "support": 0.2 },
      "confidence": 0.6
    },
    "urgency": {
      "type": "score",
      "score": 1.5,
      "probabilities": { "0": 0.1, "1": 0.3, "2": 0.6 },
      "confidence": 0.3,
      "legend": { "0": "Normal review", "1": "Timely response", "2": "Immediate human attention" }
    },
    "duplicate": { "type": "noul", "noul": 0.8 }
  },
  "usage": { "input_tokens": 120, "output_tokens": 0 }
}

回答の名前は質問の名前と一致します。Choice はオプション名、Score は小数値になることがあります。noul は真である確率で、0 から 1 の値です。confidence は別のモデル統計であり、選択されたオプションの確率とは限りません。返された model は要求した ID と異なることがあります。比較するときは両方を記録してください。トークン数などの任意の値が欠落または null の場合は、不明であり 0 ではありません。

成功レスポンスの本文に System One の billing、request_id、replayed フィールドは追加されません。モデルが同名のフィールドを返した場合、System One の会計情報ではなくモデルのデータとして扱ってください。core SDK と systemOneAdapter は Noul を { type: 'boolean', probability } に、トークン使用量を camelCase に正規化します。生のヘッダーが必要な場合は Fetch か、公式 TypeSafe クライアントの withResponse() を使ってください。

レスポンスヘッダー

課金、リクエスト ID、リプレイ状態は、これらのヘッダーとコンソールの利用記録から読みます。似た名前の本文フィールドは使いません。レスポンスは Cache-Control: no-store です。これは明示的な 24 時間の冪等ウィンドウとは別物です。

ブラウザからの利用と CORS

/v1/* は未認証の OPTIONS プリフライトに対応し、ステータス 204、Access-Control-Allow-Origin: *、許可メソッド GET, POST, OPTIONS、許可リクエストヘッダー Authorization, Content-Type, Idempotency-Key を返します。上記の追跡、クレジット、レート制限、リトライ、リプレイ、エラー分類のヘッダーはブラウザの JavaScript から参照できます。これは Bearer 認証であり、オリジン跨越の Cookie 認証ではありません。Access-Control-Allow-Credentials は有効になっていません。CORS 対応は、長寿命のアカウントキーを公開のブラウザコードに埋め込むことを安全にはしません。

抽出

本文に fields を含めると、意思決定の質問への回答ではなく型付きの値を抽出します。{ model, state, fields } に、任意の images、reference_date、options を添えて 1 回だけ送ります。認証、課金、返金、検証はこのエンドポイントのままです。フィールド数で価格は変わりません。公開の抽出モデル名は clairic です。TypeScript SDK も同じ契約を client.extract() で公開しています。Clairic 抽出を参照してください。

{
  "model": "clairic",
  "state": "INVOICE INV-2291\nFrom: Northwind Supply\nIssued: 2026-09-02\nTotal due: 1080.00",
  "fields": {
    "invoice_number": { "type": "text" },
    "total": { "type": "number", "decimals": 2 }
  }
}

意思決定の本文は questions を使い、抽出リクエストではありません。抽出モデルは questions を拒否し、意思決定モデルは fields を拒否します。SDK の evaluate() に fields を渡さないでください。

内部リンク

TypeScript SDK を始める、意思決定プリミティブ、API エラーコード、冪等キー（Idempotency key）、API バージョニングも参照してください。