プロンプトひとつではじめる。

クイックスタート#

npx -y scaledthought@0.3 init --region us

npx -y scaledthought@0.3 billing topup --amount-usd 20

curl "$ST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

認証#

キーをBearerトークンとして送信します。キーは一つのリージョンに限定され、独自の予算を設定できます。ベースURLはリージョンのホストで、.env に ST_BASE_URL として保存されます：https://api.us.scaledthought.com/v1（カナダの https://api.ca.scaledthought.com/v1 は近日公開）。

Authorization: Bearer $ST_API_KEY
Content-Type: application/json

チャット補完#

POST /v1/chat/completions はOpenAIのリクエスト形式を受け付けます。モデルIDは npx -y scaledthought@0.3 models --live または /pricing で確認してください。

curl "$ST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

ストリーミング#

stream: true を指定すると、OpenAIのdelta形式でServer-Sent Eventsを受信できます。

stream = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": "Write a haiku about open weights"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

ツール呼び出し#

tools をOpenAIの形式で渡します。ツール呼び出しに対応したモデルは、標準の tool_calls を返します。対応状況と品質はモデルによって異なるため、使う前にモデルのカードを確認してください。

resp = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": "Weather in Toronto?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        },
    }],
)
print(resp.choices[0].message.tool_calls)

構造化出力#

response_format にJSONスキーマを指定します。対応しているモデルでは、デコード時に出力がスキーマに制約されます。結果を使う前に検証してください。

resp = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": invoice_text}],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "invoice", "schema": {
            "type": "object",
            "properties": {"vendor": {"type": "string"}, "total": {"type": "number"}},
            "required": ["vendor", "total"],
        }},
    },
)

Responses APIとCodex#

POST $ST_BASE_URL/responses はOpenAI Responses APIに対応しているため、Codexのようにこのプロトコルだけを使うクライアントも、ScaledThoughtをモデルプロバイダーとして使えます。受け付けるのは input（文字列、またはメッセージ、function_call と function_call_output のアイテム）、instructions、関数ツールとカスタム（自由形式）ツール、tool_choice、max_output_tokens、JSON出力用の text.format、そして stream: true（Responsesのイベント。最後は usage 付きの response.completed または response.incomplete、あるいは error 付きの response.failed）です。

ステートレスです。レスポンスは保存しないため、毎ターン会話全体を input で送り（Codexはそうしています）、previous_response_id は送らないでください。送ると 400 invalid_request が返ります。store は常にfalseです。ファイル検索などのホスト型ツールは 400 を返し、Web検索ツールは無視されます。max_output_tokens のないリクエストには、プロンプトの後に残るモデルのコンテキスト分（最大32,768トークン）の上限が適用されます。

課金はチャット補完と同じです。モデルサーバーが報告する使用量に基づくトークン単位で、クレジットから支払われます。

# ~/.codex/config.toml
model = "deepseek-v4-1-flash"  # or a model id from `npx -y scaledthought@0.3 models --live`
model_provider = "scaledthought"

[model_providers.scaledthought]
name = "ScaledThought"
base_url = "https://api.us.scaledthought.com/v1"  # your ST_BASE_URL
env_key = "ST_API_KEY"
wire_api = "responses"
model_catalog_url = "https://api.us.scaledthought.com/v1/codex/models"  # same host (and region) as base_url

Codexは環境変数から ST_API_KEY を読むため、先に ./.env をシェルに読み込んでください。wire_api = "responses" は必須です。ScaledThoughtはCodexにResponses API経由で提供しています。

model_catalog_url はCodexに、あなたのリージョンで公開中のモデルのコンテキストウィンドウを伝えるため、長いセッションを適切なタイミングで圧縮でき、編集用の apply_patch ツールも使えるようになります。リクエストのたびに公開中のモデルから生成されます。Codexはこれにキーを付けて送るため、base_url と同じホスト（あなたのリージョンのホスト）に置いてください。

モデルとベンチマーク#

GET /v1/models は、あなたのリージョンで公開中のモデルIDをOpenAIの形式で一覧表示します。呼び出せるモデルはこの一覧が正です。GET /v1/models/{id} は一つのモデルの料金、コンテキスト長、リリース日、ベンチマークスコア、公開状況を返すため、エージェントは人間がWebページを読まなくてもモデルを選べます。検索や絞り込みには npx -y scaledthought@0.3 models --live またはMCPツールの models_search を使います。人間向けには、/pricing が同じAPIから、米国で公開中のすべてのモデルとその料金を一覧表示しています。

curl "$ST_BASE_URL/models"
curl "$ST_BASE_URL/models/deepseek-v4-1-flash"

リージョンとデータ保持#

すべてのキーはそのリージョンに固定されます。米国リージョンは公開中で、カナダ（ca）は近日公開です。公開されるまで、そのAPIは応答しません。リクエストの処理とログ記録、アカウントと使用量の記録の保存は、その国の中だけで行われます。すべてのリージョンのカード決済は、米国のStripeが処理します。プロンプトと補完はレスポンスを返した後に保存されず、学習に使われることもありません。バッチとファインチューニングのファイルは30日後に、または DELETE /v1/files/{id} でそれより早く消去されます。すべてのレスポンスには x-st-region と x-st-data-retention: none が付きます。セキュリティ（または /security.json）とプライバシーポリシー （英語）を参照してください。

キーと予算#

エージェントは、1日あたりの支出上限を厳密に設けた、スコープ付きのキーを作成できます。予算に達すると、それ以上支出せずに呼び出しは402を返します。失効させたキーは、約30秒以内に使えなくなります。

npx -y scaledthought@0.3 keys create --name support-bot --budget-usd 40

スコープは inference, read, keys, billing です。キーは、自分が持っているスコープしか新しいキーに付与できません（そうでなければ 403 scope_not_allowed）。有効期限：expires_in（"30d" など）または expires_at を送ります。最長365日で、期限を過ぎたキーは 401 key_expired になります。キーが、それを作成したキーより長く有効になることはありません。

サブエージェントキー：child: true を指定すると、新しいキーは呼び出し元のキーを親として記録します。1日の予算は親のその日の残りの範囲内に収まり、レート制限と有効期限は親を超えず、管理できるのは自分のサブキーだけです。キーを失効させると、その下にあるすべてのキーも失効します。

ローテーション：POST /v1/keys/{id}/rotate は、同じ名前、スコープ、予算、制限を持つ置き換え用のキーを発行し、一度だけ返します。古いキーは grace の間（デフォルト24h、"0"〜"7d"）使い続けられます。自己失効：DELETE /v1/keys/self は、呼び出し元のキーとそのサブエージェントキーを失効させます。スコープは不要なので、漏えいを疑ったエージェントはすぐに対処できます。

npx -y scaledthought@0.3 keys create --name sub-agent --child --scopes inference --budget-usd 2 --expires-in 12h
npx -y scaledthought@0.3 keys rotate key_… --grace 24h
npx -y scaledthought@0.3 keys revoke-self

キーとデータの保護について詳しくは：セキュリティ。

クレジットと承認#

利用料はプリペイドクレジットから支払われます。一回のチャージは$20〜$2,000、24時間あたり最大$2,000、同時に開いておける承認リンクは2件までです。エージェントがチャージ（デフォルトは$20）を依頼すると、approval_url が返ります。これは入金ページで、人間のユーザーが金額を確認または変更し、自動チャージをオンにでき、カードで支払います。支払いが確認されるとクレジットが反映され、領収書をメールでお送りします。この承認なしに請求されることは一切ありません。クレジットに有効期限はありません。クレジットがなくなると、リクエストは残高と必要額を添えて 402 insufficient_credits を返します。

npx -y scaledthought@0.3 billing topup --amount-usd 20

自動チャージは任意ですが、おすすめです。残高がしきい値（デフォルト$5）を下回ると、保存済みのカードから一定額（デフォルト$20）が追加されるため、エージェントが止まることがありません。人間のユーザーは、任意のチャージの入金ページでオンにするか、何も購入せずに自動チャージ設定リンク（billing auto-reload setup）でカードを保存してオンにできます。入金は24時間あたり$2,000までです。オンにする場合や上限を引き上げる場合は新たな承認が必要で、オフにする場合や引き下げる場合は不要です。チャージが拒否されると自動チャージは自動的にオフになり、次の402でエージェントに新しいリンクを取得するよう伝えます。billing status は残高と保留中のチャージを、billing transactions はすべての購入、自動チャージ、請求を表示します。

npx -y scaledthought@0.3 billing topup --amount-usd 20 --auto-reload-below 5 --auto-reload-amount 20
npx -y scaledthought@0.3 billing auto-reload setup --below 5 --amount 20   # no purchase: they save a card
npx -y scaledthought@0.3 billing auto-reload off

通知とWebhook#

レスポンスには、カンマ区切りのコードを持つ x-st-notice が付くことがあります：low_balance（残高が$5未満のアカウント）。これを受け取ったエージェントは、何を承認すればよいかを人間のユーザーに伝えてください。GET /v1/account、MCPの account_status、status、doctor も、伝えるべき文言とともに同じコードを表示します。

Webhookは、同じシグナル（balance.low、key.expiring、budget.exhausted）をプッシュで送ります。エンドポイントは、ポート443の公開https URLである必要があります。各POSTには x-st-signature: t=…,v1=… が付きます。これは <t>.<raw body> のHMAC-SHA256で、エンドポイントの署名シークレットを鍵とします。シークレットは追加時に一度だけ表示されます。配信先はURLのホスト場所を問わず（アカウントのリージョン外であっても）あなたのURLで、含まれるのは id、type、created_at、region、account_id、data だけです。ID、整数のマイクロドル金額、日数、タイムスタンプのみで、プロンプト、名前、メールアドレスは含まれません。イベントごとの data：balance.low {balance_micros, threshold_micros}、key.expiring {key_id, expires_at}、budget.exhausted {scope, key_id, budget_micros, spent_today_micros, resets_at}。失敗した配信は、バックオフを挟みながら約2日間再試行されます。

npx -y scaledthought@0.3 webhooks add https://hooks.example.com/st --events balance.low,budget.exhausted

任意のリクエストヘッダー：x-st-app は使用量の記録にアプリ名を残し（公開はされません）、x-st-session は一つの会話を同じレプリカに留めて、キャッシュされたプレフィックスを再利用できるようにします（メモリ上のみで、保存されません）。カナダでは、リクエストが他国にあふれ出すことはありません。モデルのすべてのレプリカが混雑している場合、リクエストは少し待機した後、Retry-After 付きの 429 capacity_exhausted を受け取ります。

バッチ推論#

リクエストのJSONLファイルをアップロードすると、通常価格の50%で結果を受け取れます。バッチは24時間の完了期間内で実行され、通常はその期間内に終わりますが、期限内の完了は保証されません。FilesとBatchesのエンドポイントはOpenAIの仕様に沿っているため、client.batches.create が動作します。すべての行は事前に検証されるため、不正なファイルは数秒以内にエラーになります。

batch_file = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
    input_file_id=batch_file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
# later
batch = client.batches.retrieve(batch.id)
results = client.files.content(batch.output_file_id).text

埋め込み#

POST /v1/embeddings を埋め込みモデルで呼び出します（モデルは models --live --modality embedding で探せます）。入力は文字列または文字列の配列です。

vecs = client.embeddings.create(model="<embedding-model-id>", input=["open weights", "served hot"])

ファインチューニング#

あなた自身の例でLoRAアダプターを学習させます。結果は、あなたのアカウントだけが呼び出せるプライベートなモデルIDで、ベースモデルと同じレプリカで提供され、ベースモデルのトークン単価で課金されます。学習できるのは、あなたのリージョンにある当社のGPUで動いているベースモデルだけで、アダプターはダウンロードできません。学習は学習トークン1Mあたり（データセットのトークン数 × エポック数）で課金され、ジョブのレスポンスには、実行前に見積もりが含まれます。プリペイドクレジットから支払われます。料金を参照してください。

f = client.files.create(file=open("examples.jsonl", "rb"), purpose="fine-tune")
job = client.fine_tuning.jobs.create(model="<base-id>", training_file=f.id, suffix="triage")
# poll
job = client.fine_tuning.jobs.retrieve(job.id)
resp = client.chat.completions.create(model=job.fine_tuned_model, messages=[...])

MCPサーバー#

リモートMCPは、あなたのリージョンのAPIホストにあります：https://api.us.scaledthought.com/mcp（カナダの https://api.ca.scaledthought.com/mcp は近日公開。Streamable HTTP、2026-07-28仕様）。APIキーをBearerトークンとして認証します。MCPではアカウントを作成できません。先に npx -y scaledthought@0.3 init または POST /v1/accounts でサインアップしてください。その後、npx -y scaledthought@0.3 mcp があなたのリージョン用の正確なコマンドと設定を表示します。エージェントが使えるツールは次のとおりです：

npx -y scaledthought@0.3 mcp

CLI#

npx -y scaledthought@0.3 <command> として実行します。stdoutが端末でない場合（または --json 指定時）、出力はJSONになります。エラーは code、message、hint を持つ一行のJSONとしてstderrに出力されます。対話的な入力は一切求めません。キーは ST_API_KEY または ./.env から読み込み、フラグからは受け取りません。

APIリファレンス#

レート制限#

制限はキーごとです。制限を超えると、呼び出しは秒単位の Retry-After ヘッダー付きで 429 rate_limit_exceeded を返します。アカウントで最初にクレジットを購入するまでは、キーの制限を下げることはできますが、上げることはできません。

エラー#

APIのエラーは {"error":{"message","type","code"}} です。CLIのエラーには hint が加わり、ゼロ以外の終了コードで終了します。