一条提示词即可开始。

快速入门#

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 token 发送。密钥限定于一个区域，并且可以有自己的预算。base URL 是你所在区域的主机，以 ST_BASE_URL 保存在 .env 中：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 的请求格式。请使用来自 npx -y scaledthought@0.3 models --live 或 /pricing 的模型 id。

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="")

工具调用#

以 OpenAI 格式传入 tools。支持工具调用的模型会返回标准的 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)

结构化输出#

使用带 JSON schema 的 response_format。在支持该功能的模型上，输出会在解码时被约束为符合该 schema。依赖结果之前请先进行验证。

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；网页搜索工具会被忽略。没有 max_output_tokens 的请求，上限为模型上下文在你的提示词之后剩余的长度，最多 32,768 个 token。

计费方式与对话补全相同：按 token 计费，依据模型服务器报告的用量，从你的额度中支付。

# ~/.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 加载到 shell 中。wire_api = "responses" 是必需的：ScaledThought 通过 Responses API 为 Codex 提供服务。

model_catalog_url 告诉 Codex 你所在区域已上线模型的上下文窗口，使它能及时压缩长会话，并为它提供 apply_patch 编辑工具。它在每次请求时根据已上线的模型生成；Codex 会随请求发送你的密钥，所以请让它与 base_url 使用同一个主机（你所在区域的主机）。

模型与基准测试#

GET /v1/models 以 OpenAI 的格式列出你所在区域已上线的模型 id。这个列表就是你能调用哪些模型的准确依据。GET /v1/models/{id} 返回单个模型的价格、上下文长度、发布日期、基准测试分数和上线状态，让智能体无需有人去阅读网页就能做出选择。如需搜索和筛选，请使用 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）以及隐私政策 （英文）。

密钥与预算#

智能体可以创建限定范围的密钥，并设置严格的每日支出上限。达到预算后，调用会返回 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 后，新密钥会把调用它的密钥记录为父密钥。它的每日预算不超过父密钥当天剩余的预算，速率限制和有效期不高于父密钥，并且只能管理自己的子密钥。吊销一个密钥会同时吊销它下面的所有密钥。

轮换：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}。投递失败会以退避方式重试约两天。

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，与其基础模型在相同的副本上提供服务，并按基础模型的 token 单价计费。只有在你所在区域、运行在我们自有 GPU 上的基础模型才能训练，适配器无法下载。训练按每 1M 训练 token（数据集 token × 轮数）计费；任务响应会在任何运行开始之前给出预估费用。从预付额度中支付。参见价格。

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 token 进行认证。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；错误是 stderr 上的一行 JSON，包含 code、message 和 hint。不会出现任何交互式提示。密钥来自 ST_API_KEY 或 ./.env，从不来自命令行参数。

API 参考#

速率限制#

限制按密钥计算。超过限制时，调用会返回 429 rate_limit_exceeded，并带有以秒为单位的 Retry-After 头。在账户首次购买额度之前，密钥只能调低限制，不能调高。

错误#

API 错误的格式为 {"error":{"message","type","code"}}。CLI 错误会额外包含 hint，并以非零状态码退出。