API リファレンス

API リファレンス

TypeSafe 評価エンドポイントの完全な HTTP API リファレンス。

型付きの questions マップに対して state を評価し、質問ごとに 1 つずつ構造化された answers を返します。入門ガイドはプリミティブから始めてください。

評価エンドポイント

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

リクエストボディ

すべてのリクエストの最上位の形です。questions マップの各エントリは、自分で名前を付けた型付きの質問です。

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

質問の種類

Question は 3 つの型のいずれかで、type フィールドで決まります。3 つとも type と instructions を共有し、それぞれが独自の criteria を追加します。

instructions プロパティは文字列・オブジェクト・配列のいずれかです。追加のコンテキストや、参照が必要なデータを伴う長い質問は、構造化オブジェクトに分割できます。質問を 1 つのフィールドに、データを他のフィールドに置き、データフィールドをバッククォートで名前参照します。入れ子になった state の値を質問から指すのと同じ要領です：

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

詳しくは質問で構造を使うを参照してください。

Noul

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

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": {
        "true": "Explicitly time-sensitive",
        "false": "No urgency expressed"
      }
    }
  }
}

Choice

自分で定義した選択肢の集合から 1 つを選びます。選ばれた選択肢と完全な確率分布を返します。

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Score

自分で定義したルーブリックに沿って状態を評価します。各レベルにまたがる、確率で重み付けした値を返します。

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

レスポンスボディ

質問ごとに 1 つの答えを、指定したものと同じ id で返します。

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

答えの種類

すべての答えは、対応する質問と一致する type を持ちます。Choice と Score の答えはさらに、その答えの確率分布から導かれた 0 から 1 の間の confidence を持ちます。詳しくは信頼度を参照してください。

Noul の答え

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

Choice の答え

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

Score の答え

{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

エラー

エラーは標準の HTTP ステータスコードを使い、何が問題だったかを説明する JSON ボディを伴います。

レート制限の扱い

429 Too Many Requests または 529 Overloaded のレスポンスを受け取ったときは、すぐに再試行せず、指数バックオフでリクエストを再試行してください。当社のクライアント SDK はこれを自動で処理するので、当社の SDK をその既定の再試行ポリシーで使っているなら追加の対応は不要です。