HTTP APIリファレンス

エンドポイント

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

stateに型付きquestionsのマップを送信し、質問ごとに1つのanswerを受け取ります。

リクエストボディ

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}

フィールド	型	必須	説明
state	string | object | array	はい	評価対象のコンテンツ。テキストの場合はプレーンな文字列、チャットログ、レコード、またはアプリケーションの現在の状態などの構造化データの場合はその形式で指定します
model	string	はい	リクエストを処理するモデル。jev-latest、TypeSafe のフラッグシップモデルを使用します。他のモデルやエイリアスについては、公式の Models ページを参照してください
questions	map<string, Question>	はい	型付き質問のマップ

questionsでキーを選択すると、各回答は同じキーの下に戻ってきます。このキーは基盤モデルには送信されず、推論でも使用されないため、ビジネスドメインに合わせて命名できます（department、is_urgent）。

3つの質問タイプ

A Questionはtypeフィールドによって区別され、3種類あります。これら3つはすべてtypeとinstructionsを共有し、それぞれが独自のcriteriaを追加します。

instructions の型は string | object | array です。

noul — はい/いいえの判断

はい/いいえの質問。回答が「はい」である確率を返します。

{
  "is_urgent": {
    "type": "noul",
    "instructions": "Does this convey urgency?",
    "criteria": {
      "true": "Explicitly time-sensitive",
      "false": "No urgency expressed"
    }
  }
}

criteria は省略可能で、「yes」と「no」がそれぞれ何を意味するかを説明します：

Key	説明
true	1に近づく値（「はい」）の意味
false	0に近づく値（「いいえ」）の意味

選択 — オプションから選ぶ

定義したセットから1つのオプションを選択し、選択したオプションと完全な確率分布を返します。

{
  "department": {
    "type": "choice",
    "instructions": "Which team should handle this?",
    "criteria": {
      "billing": "Payments, invoicing, refunds",
      "technical": "Bugs, outages, integrations",
      "sales": "Pricing, upgrades, new accounts"
    }
  }
}

criteria が必要で、型は map<string, string | null> です：オプション名がルールの説明にマッピングされています。オプションに追加の説明が必要ない場合は、null を値として使用します。

スコア — 尺度に沿った評価

定義したルーブリックに基づいてstateを評価し、各レベルにわたる確率加重値を返してください。

{
  "frustration": {
    "type": "score",
    "instructions": "How frustrated is the customer?",
    "criteria": ["Calm", "Frustrated", "Very angry"]
  }
}

criteria は必須であり、レベルの説明からなる順序付き配列です。少なくとも2つのレベルを含める必要があります。

応答ボディ

各質問は、あなたが指定した id をキーとして、1つの回答を生成します。

{
  "model": "jev-latest",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.92
    }
  },
  "usage": { "input_tokens": 312, "output_tokens": 48 }
}

フィールド	型	説明
model	string	評価を実行したモデル
answers	map<string, Answer>	各質問に対する回答。questionsと同じキーで構成
usage	object	リクエストのトークン使用量: input_tokens, output_tokens

種類別の回答形状

すべての回答は、その質問に一致するtypeを伴います。choiceおよびscoreの回答は、その回答の確率分布（公式の信頼性ページを参照）から導出されるconfidence（0から1の間）も伴います。

noul answer

フィールド	型	説明
noul	number	0（いいえ）から1（はい）までのyes/noの回答

{ "type": "noul", "noul": 0.92 }

選択回答

フィールド	型	説明
choice	string	最確率のオプション
probabilities	map<string, number>	オプションごとの確率；合計は1
confidence	number	モデルの確信度。確率から導出

{
  "type": "choice",
  "choice": "technical",
  "probabilities": { "billing": 0.08, "technical": 0.85, "sales": 0.07 },
  "confidence": 0.82
}

スコア回答

フィールド	型	説明
score	number	確率加重値。レベル間に値が収まる可能性がある
legend	map<string, string>	各レベルインデックスをその説明にマッピングする
probabilities	map<string, number>	レベルごとの確率（文字列キー）；合計は1になる
confidence	number	確率から導出された、モデルの確信度

{
  "type": "score",
  "score": 1.6,
  "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
  "probabilities": { "0": 0.05, "1": 0.3, "2": 0.65 },
  "confidence": 0.78
}

scoreとprobabilitiesの関係に注目してください：3つのレベル確率は 0.05 / 0.3 / 0.65 で、scoreに 1.6 の重み付けされています。したがって、scoreは整数である必要はありません — これはまさに、choiceと区別される点です。choiceは1つの離散オプションを提供しますが、scoreは「2つのレベルの間にある」ことを表現できます。

エラー

エラーは標準的なHTTPステータスコードを使用し、何が悪かったかを説明するJSONボディを含みます。

ステータス	意味
401 Unauthorized	APIキーが不足しているか無効です。Authorizationヘッダーを確認してください
422 Unprocessable Entity	リクエストボディの検証に失敗しました。例えば、必須フィールドが不足しているか、質問の形式が不正です。ボディには問題のあるフィールドが示されています
429 Too Many Requests	レート制限を超過しました。短い遅延後に再試行してください
529 Overloaded	TypeSafeが一時的に過負荷状態です。短い遅延後に再試行してください

レートリミットの処理

429または529の場合、即時再試行するのではなく、指数関数的バックオフを用いて再試行してください。公式SDKを使用している場合、そのデフォルトの再試行ポリシーがこれを自動的に処理するため、追加のコードは不要です。