Comece com um prompt.

Início rápido#

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"}]
  }'

Autenticação#

Envie sua chave como bearer token. As chaves valem para uma região e podem ter o próprio orçamento. A URL base é o host da sua região, salvo no .env como ST_BASE_URL: https://api.us.scaledthought.com/v1 (o do Canadá, https://api.ca.scaledthought.com/v1, chega em breve).

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

Chat completions#

POST /v1/chat/completions aceita o formato de requisição da OpenAI. Use um id de modelo de npx -y scaledthought@0.3 models --live ou de /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"}]
  }'

Streaming#

Defina stream: true para receber server-sent events no formato delta da OpenAI.

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

Chamada de ferramentas#

Passe tools no formato da OpenAI. Os modelos que suportam chamada de ferramentas retornam tool_calls padrão. O suporte e a qualidade variam de modelo para modelo, então confira o card do modelo antes de depender disso.

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)

Saída estruturada#

Use response_format com um JSON schema. Nos modelos que suportam isso, a saída é restrita ao schema durante a decodificação. Valide o resultado antes de depender dele.

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 e Codex#

POST $ST_BASE_URL/responses fala a OpenAI Responses API, então clientes que usam apenas esse protocolo, como o Codex, podem usar a ScaledThought como provedor de modelos. Ele aceita input (uma string, ou mensagens e itens function_call e function_call_output), instructions, ferramentas de função e personalizadas (formato livre), tool_choice, max_output_tokens, text.format para saída em JSON e stream: true (eventos da Responses API, terminando com response.completed ou response.incomplete com o seu usage, ou response.failed com um error).

Ele não guarda estado. Não armazenamos nenhuma resposta, então envie a conversa inteira em input a cada turno (o Codex faz isso) e não use previous_response_id, que retorna 400 invalid_request; store é sempre false. Ferramentas hospedadas, como busca em arquivos, retornam 400; uma ferramenta de busca na web é ignorada. Requisições sem max_output_tokens recebem como limite o que sobra do contexto do modelo depois do seu prompt, no máximo 32.768 tokens.

A cobrança é a mesma de chat completions: por token, a partir do uso informado pelo servidor do modelo, paga com seus créditos.

# ~/.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

O Codex lê ST_API_KEY do ambiente, então carregue o ./.env no shell antes. wire_api = "responses" é obrigatório: a ScaledThought serve o Codex pela Responses API.

model_catalog_url informa ao Codex as janelas de contexto dos modelos no ar na sua região, para que ele compacte sessões longas a tempo, e dá a ele a ferramenta de edição apply_patch. Ele é gerado a partir dos modelos no ar a cada requisição; o Codex envia sua chave junto, então mantenha-o no mesmo host que base_url (o da sua região).

Modelos e benchmarks#

GET /v1/models lista os ids dos modelos no ar na sua região, no formato da OpenAI. Essa lista é a referência do que você pode chamar. GET /v1/models/{id} retorna o preço, o tamanho de contexto, a data de lançamento, as pontuações de benchmark e o status de um modelo, para que um agente possa escolher sem que um humano leia uma página web. Para buscar e filtrar, use npx -y scaledthought@0.3 models --live ou a ferramenta MCP models_search. Para pessoas, /pricing lista todos os modelos no ar nos EUA com seus preços, a partir da mesma API.

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

Regiões e retenção#

Cada chave fica vinculada à sua região. A região dos EUA está aberta agora; o Canadá (ca) chega em breve; a API dele não responde até ele abrir. As requisições são atendidas e registradas em logs, e os registros de conta e de uso são armazenados, apenas naquele país. Os pagamentos com cartão de todas as regiões são processados pela Stripe nos EUA. Prompts e completions não são armazenados depois que a resposta é retornada e nunca são usados para treinamento. Os arquivos de lote e de fine-tuning são apagados após 30 dias, ou antes com DELETE /v1/files/{id}. Toda resposta traz x-st-region e x-st-data-retention: none. Veja segurança (ou /security.json) e a Política de Privacidade (em inglês).

Chaves e orçamentos#

Os agentes podem criar chaves com escopo e limites rígidos de gasto diário. Quando um orçamento é atingido, as chamadas retornam 402 em vez de gastar mais. Uma chave revogada para de funcionar em cerca de 30 segundos.

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

Escopos são inference, read, keys, billing. Uma chave só pode dar a uma nova chave os escopos que ela mesma tem (caso contrário, 403 scope_not_allowed). Expiração: envie expires_in (como "30d") ou expires_at, até 365 dias; depois disso a chave recebe 401 key_expired. Uma chave nunca dura mais que a chave que a criou.

Chaves de subagente: com child: true, a nova chave registra a chave que fez a chamada como sua mãe. O orçamento diário dela cabe no que resta hoje à chave mãe, seus limites de taxa e sua expiração não passam dos da mãe, e ela só pode gerenciar as próprias subchaves. Revogar uma chave revoga todas as chaves abaixo dela.

Rotação: POST /v1/keys/{id}/rotate cria uma substituta com o mesmo nome, escopos, orçamento e limites, retornada uma única vez. A chave antiga continua funcionando durante grace (padrão 24h, de "0" a "7d"). Autorrevogação: DELETE /v1/keys/self revoga a chave que fez a chamada e suas chaves de subagente, sem exigir escopo, para que um agente que suspeite de um vazamento possa agir na hora.

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

Mais sobre como as chaves e os dados são protegidos: segurança.

Créditos e aprovação#

O uso é pago com créditos pré-pagos, de $20 a $2,000 por recarga, no máximo $2,000 a cada 24 horas e 2 links de aprovação abertos ao mesmo tempo. O agente pede uma recarga ($20 por padrão) e recebe uma approval_url: uma página de pagamento em que a pessoa responsável confirma ou altera o valor, pode ativar a recarga automática e paga com cartão. Os créditos entram assim que o pagamento é confirmado, e enviamos um recibo por e-mail. Nada é cobrado sem essa aprovação. Os créditos não expiram. Quando acabam, as requisições retornam 402 insufficient_credits com o saldo e o valor necessário.

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

A recarga automática é opcional e recomendada: quando o saldo cai abaixo de um limite (padrão $5), o cartão salvo adiciona um valor definido (padrão $20), para que o agente nunca fique parado. A pessoa responsável a ativa na página de pagamento de qualquer recarga, ou sem comprar nada, por um link de configuração da recarga automática (billing auto-reload setup), onde salva um cartão. As cargas são limitadas a $2.000 a cada 24 horas. Ativá-la ou aumentar qualquer limite exige uma nova aprovação; desativá-la ou reduzi-la, não. Se uma recarga for recusada, a recarga automática se desativa sozinha e o próximo 402 diz ao agente para obter um novo link. billing status mostra o saldo e as recargas pendentes; billing transactions lista cada compra, recarga e cobrança.

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

Avisos e webhooks#

As respostas podem trazer x-st-notice com códigos separados por vírgula: low_balance (uma conta com saldo abaixo de $5). Um agente que vê um desses códigos deve dizer à pessoa responsável o que aprovar. GET /v1/account, o account_status do MCP, status e doctor mostram os mesmos códigos com o texto a repassar.

Os webhooks enviam os mesmos sinais por push: balance.low, key.expiring e budget.exhausted. Os endpoints precisam ser URLs https públicas na porta 443. Cada POST traz x-st-signature: t=…,v1=…, um HMAC-SHA256 de <t>.<raw body> com a chave de assinatura do endpoint, exibida uma única vez quando você o adiciona. As entregas vão para a sua URL onde quer que ela esteja hospedada, mesmo fora da região da sua conta, e trazem apenas id, type, created_at, region, account_id e data: ids, valores inteiros em micro-dólares, contagens de dias e timestamps, nunca prompts, nomes ou e-mails. data por evento: balance.low {balance_micros, threshold_micros}, key.expiring {key_id, expires_at}, budget.exhausted {scope, key_id, budget_micros, spent_today_micros, resets_at}. Entregas que falham são reenviadas com backoff por cerca de dois dias.

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

Cabeçalhos de requisição opcionais: x-st-app dá nome ao seu app nos registros de uso (não é publicado), e x-st-session mantém uma conversa na mesma réplica para que o prefixo em cache seja reaproveitado (só em memória, nunca armazenado). No Canadá, as requisições nunca transbordam para outro país: quando todas as réplicas de um modelo estão ocupadas, a requisição espera um pouco e depois recebe 429 capacity_exhausted com Retry-After.

Inferência em lote#

Envie um arquivo JSONL de requisições e receba os resultados por 50% do preço normal. Os lotes rodam numa janela de conclusão de 24 horas e normalmente terminam dentro dela, mas a conclusão no prazo não é garantida. Os endpoints de Files e Batches seguem os da OpenAI, então client.batches.create funciona. Cada linha é validada logo de início, então um arquivo inválido falha em segundos.

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

Embeddings#

POST /v1/embeddings com um modelo de embedding (encontre um com models --live --modality embedding). A entrada pode ser uma string ou um array de strings.

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

Fine-tuning#

Treine um adaptador LoRA com os seus próprios exemplos. O resultado é um id de modelo privado que só a sua conta pode chamar, servido nas mesmas réplicas do modelo base e cobrado pelo preço por token do modelo base. Só é possível treinar modelos base que rodam nas nossas próprias GPUs na sua região, e os adaptadores não podem ser baixados. O treinamento é cobrado por 1M de tokens de treinamento (tokens do dataset × épocas); a resposta do job inclui uma estimativa antes de qualquer execução. Pago com créditos pré-pagos. Veja preços.

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=[...])

Servidor MCP#

MCP remoto no host da API da sua região: https://api.us.scaledthought.com/mcp (o do Canadá, https://api.ca.scaledthought.com/mcp, chega em breve; Streamable HTTP, especificação 2026-07-28). Autentique-se com sua chave de API como bearer token. O MCP não cria contas: cadastre-se antes com npx -y scaledthought@0.3 init ou POST /v1/accounts, e então npx -y scaledthought@0.3 mcp mostra o comando e a configuração exatos para a sua região. O agente recebe estas ferramentas:

npx -y scaledthought@0.3 mcp

CLI#

Execute como npx -y scaledthought@0.3 <command>. A saída é JSON sempre que o stdout não é um terminal (ou com --json), e os erros são uma linha JSON no stderr com code, message e hint. Nada pede interação. As chaves vêm de ST_API_KEY ou de ./.env, nunca de flags.

Referência da API#

Limites de taxa#

Os limites são por chave. Acima do limite, as chamadas retornam 429 rate_limit_exceeded com um cabeçalho Retry-After em segundos. Até a primeira compra de créditos da conta, as chaves podem reduzir seus limites, mas não aumentá-los.

Erros#

Os erros da API são {"error":{"message","type","code"}}. Os erros da CLI acrescentam um hint e saem com código diferente de zero.