概要 / reference
API・SDK
エンドポイントは1つだけ。state と questions を送ると、質問 ID ごとの answers が返ります。ここでは実装前に押さえておく要点をまとめます。正確な仕様は必ず公式 API リファレンスで確認してください。
エンドポイント
HTTP評価エンドポイント
POST https://api.typesafe.ai/v1/systemone Authorization: Bearer <API_KEY> Content-Type: application/json
curl公式クイックスタートより
curl -X POST https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": "Help! My payouts have been failing for 3 days.",
"model": "jev-latest",
"questions": {
"is_urgent": {
"type": "noul",
"instructions": "Does this convey urgency?"
}
}
}'
API キーはコンソールで発行します。Web アプリでは API 資格情報を必ずサーバー側に置いてください。
リクエスト／レスポンスの構造
質問 ID をキーにした対称な形になっています。送ったキーと同じキーで答えが返ります。
state · 必須 · string | object | array評価する内容テキスト、または会話ログ・レコード・アプリの状態などの構造化データ
model · 必須 · string
"jev-latest"リクエストを処理するモデルquestions · 必須 · map<string, Question>型付き質問のマップ
noul
instructions 必須 ／ criteria {true, false} 任意choice
instructions 必須 ／ criteria 必須：選択肢 → 説明（または null）のマップscore
instructions 必須 ／ criteria 必須：順序付きのレベル配列（2つ以上）instructions と criteria の各エントリは、文字列・オブジェクト・配列のいずれでも可。質問 ID はモデルには送られず、推論には使われません。model · string評価を行ったモデル
answers · map<string, Answer>質問と同じ ID をキーにした答え
noul answer
type, noul（0 = no 〜 1 = yes）choice answer
type, choice, probabilities（合計1）, confidencescore answer
type, score, legend, probabilities（合計1）, confidenceusage · object
input_tokens, output_tokensリクエストのトークン使用量押さえておく制限値
TOKEN BUDGET / REQUEST
約 32,000
state と全質問で共有するトークン予算。英語でおよそ15万文字。1リクエストの質問数の上限は、この予算だけで決まる。
CHOICE OPTIONS
最大 255
1つの Choice 質問に入れられる選択肢の数。1つ足すコストは数トークン。
SCORE LEVELS
2 〜 10
1つの Score 質問のレベル数。区別して記述できる数だけ使う。
LATENCY
約 100 ms
公式ドキュメントによる「多くのクエリ」の完了時間の目安。質問を足してもほぼ変わらない。
料金やレート制限はプランにより変わるため、本資料では扱いません。公式サイトとコンソールで確認してください。
エラーとリトライ
エラーは標準的な HTTP ステータスコードと、原因を説明する JSON ボディで返ります。
| ステータス | 意味 | 対処 |
|---|---|---|
401 Unauthorized | API キーがない／無効 | Authorization ヘッダーを確認 |
422 Unprocessable Entity | リクエストボディが検証に失敗（必須フィールドの欠落、質問の形式不正など） | ボディに問題のフィールドが示される。リトライしても直らない |
429 Too Many Requests | レート制限を超過 | 少し待って、指数バックオフでリトライ |
529 Overloaded | TypeSafe 側が一時的に過負荷 | 少し待って、指数バックオフでリトライ |
SDK なら自動でリトライされる公式 SDK は既定のリトライポリシーで 429 / 529 を自動処理します。Python SDK の
RetryPolicy の既定値は、最大リトライ 2 回、初期バックオフ 0.5 秒（上限 5 秒、ジッターあり）、対象ステータスは 408・429・5xx、タイムアウト 30 秒、Retry-After ヘッダーを尊重、です。失敗の切り分け結果がおかしいときは、state・質問・候補・答え・合成ロジック・観測された結果をそのまま確認し、「証拠の不足」「モデルの誤り」「コードの誤り」「サービスの障害」を分けて考えます。
SDK
Python と JavaScript / TypeScript の公式 SDK があり、質問と答えに型が付きます。どちらも環境変数 TYPESAFE_API_KEY を読み、既定で jev-latest を呼びます。
Python（3.10 以上）pip / uv
pip install typesafe-sdk # または uv add typesafe-sdk
Python同期クライアント
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
with TypeSafeClient() as client:
response = client.system_one(
state={
"ticket_message": "My flight was cancelled. Can I get a refund?",
"refund_policy": "Cancelled flights are eligible for a full refund.",
},
questions={
"refund_requested": Noul(
instructions="Does `ticket_message` request a refund?",
),
"request_type": Choice(
instructions="What is the main request in `ticket_message`?",
criteria={
"refund": "The customer wants money returned.",
"rebooking": "The customer wants a replacement flight.",
"information": "The customer is asking for information only.",
},
),
},
)
print(response.answers["refund_requested"].noul)
print(response.answers["request_type"].choice)
JavaScript / TypeScript（Node.js 20 以上）npm
npm install @typesafe-ai/sdk
TypeScript答えの型は質問から推論される
import { choice, TypeSafeClient } from "@typesafe-ai/sdk";
const client = new TypeSafeClient();
const response = await client.systemOne({
state: { document: "I was charged twice. Please fix this ASAP." },
questions: {
category: choice("What is this ticket about?", {
billing: null,
technical: null,
other: null,
}),
},
});
console.log(response.answers.category.choice);
- Python同期の
TypeSafeClientと非同期のAsyncTypeSafeClient。ScoreAnswerのprobabilities/legendは、JSON と違い整数キー。 - JavaScript
choice()/score()/noul()のヘルパー関数。ESM・CommonJS・TypeScript 宣言を同梱。
コーディングエージェント用スキル
Claude Code や Codex などのコーディングエージェントに、TypeSafe のリクエスト／レスポンスの形と設計作法（質問をまとめて聞く、分解する、確信度で分岐する）を教えるスキルが公開されています。
Claude Codeplugin
claude plugin marketplace add typesafe-ai/skills claude plugin install typesafe@typesafe-ai
その他のエージェントnpx
npx skills add typesafe-ai/skills --skill typesafe-ai # プロンプトでエージェントを選択。-g でグローバルにインストール