Inizia con un solo prompt.

Guida rapida#

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

Autenticazione#

Invia la tua chiave come bearer token. Le chiavi sono limitate a una regione e possono avere un proprio budget. Il base URL è l'host della tua regione, salvato in .env come ST_BASE_URL: https://api.us.scaledthought.com/v1 (quello del Canada, https://api.ca.scaledthought.com/v1, è in arrivo).

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

Chat completions#

POST /v1/chat/completions accetta il formato di richiesta di OpenAI. Usa un id di modello da npx -y scaledthought@0.3 models --live o da /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#

Imposta stream: true per ricevere server-sent events nel formato delta di 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="")

Chiamata di strumenti#

Passa tools nel formato di OpenAI. I modelli che supportano la chiamata di strumenti restituiscono tool_calls standard. Supporto e qualità variano da modello a modello, quindi controlla la scheda di un modello prima di farci affidamento.

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)

Output strutturato#

Usa response_format con uno schema JSON. Sui modelli che lo supportano, l'output è vincolato allo schema durante la decodifica. Convalida il risultato prima di farci affidamento.

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 parla la Responses API di OpenAI, quindi i client che usano solo quel protocollo, come Codex, possono usare ScaledThought come provider di modelli. Accetta input (una stringa, oppure messaggi ed elementi function_call e function_call_output), instructions, strumenti function e custom (in formato libero), tool_choice, max_output_tokens, text.format per l'output JSON e stream: true (eventi Responses, che terminano con response.completed o response.incomplete con il relativo usage, oppure response.failed con un error).

È stateless. Non conserviamo nessuna risposta, quindi invia l'intera conversazione in input a ogni turno (Codex lo fa) e ometti previous_response_id, che restituisce 400 invalid_request; store è sempre false. Gli strumenti ospitati come la ricerca nei file restituiscono 400; uno strumento di ricerca web viene ignorato. Le richieste senza max_output_tokens ricevono come limite lo spazio che il contesto del modello lascia dopo il tuo prompt, al massimo 32.768 token.

La fatturazione è la stessa delle chat completions: per token, in base all'uso riportato dal server del modello, pagata con i tuoi crediti.

# ~/.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 legge ST_API_KEY dall'ambiente, quindi carica prima ./.env nella shell. wire_api = "responses" è obbligatorio: ScaledThought serve Codex tramite la Responses API.

model_catalog_url comunica a Codex le finestre di contesto dei modelli online nella tua regione, così compatta per tempo le sessioni lunghe, e gli fornisce il suo strumento di modifica apply_patch. Viene generato dai modelli online a ogni richiesta; Codex vi invia la tua chiave, quindi tienilo sullo stesso host di base_url (quello della tua regione).

Modelli e benchmark#

GET /v1/models elenca gli id dei modelli online nella tua regione, nel formato di OpenAI. Quell'elenco è il riferimento per sapere cosa puoi chiamare. GET /v1/models/{id} restituisce per un modello prezzi, lunghezza del contesto, data di rilascio, punteggi nei benchmark e stato online, così un agente può scegliere senza che una persona legga una pagina web. Per cercare e filtrare, usa npx -y scaledthought@0.3 models --live o lo strumento MCP models_search. Per le persone, /pricing elenca ogni modello online negli Stati Uniti con il suo prezzo, dalla stessa API.

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

Regioni e conservazione#

Ogni chiave è vincolata alla propria regione. La regione Stati Uniti è aperta ora; il Canada (ca) è in arrivo e la sua API non risponde finché non apre. Le richieste vengono servite e registrate nei log, e i dati di account e di utilizzo conservati, solo in quel paese. I pagamenti con carta per ogni regione sono elaborati da Stripe negli Stati Uniti. Prompt e completion non vengono conservati dopo che la risposta è stata restituita e non vengono mai usati per l'addestramento. I file di batch e di fine-tuning vengono cancellati dopo 30 giorni, o prima con DELETE /v1/files/{id}. Ogni risposta include x-st-region e x-st-data-retention: none. Vedi sicurezza (o /security.json) e l'Informativa sulla privacy (in inglese).

Chiavi e budget#

Gli agenti possono creare chiavi con ambiti limitati e limiti di spesa giornalieri rigidi. Quando un budget viene raggiunto, le chiamate restituiscono 402 invece di spendere ancora. Una chiave revocata smette di funzionare entro circa 30 secondi.

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

Ambiti (scopes): inference, read, keys, billing. Una chiave può dare a una nuova chiave solo gli ambiti che ha lei stessa (altrimenti 403 scope_not_allowed). Scadenza: invia expires_in (ad esempio "30d") o expires_at, fino a 365 giorni; dopo, la chiave riceve 401 key_expired. Una chiave non sopravvive mai alla chiave che l'ha creata.

Chiavi per sotto-agenti: con child: true la nuova chiave registra la chiave chiamante come chiave madre. Il suo budget giornaliero rientra in ciò che resta oggi alla chiave madre, i suoi limiti di frequenza e la sua scadenza non superano quelli della madre, e può gestire solo le proprie sotto-chiavi. Revocare una chiave revoca tutte le chiavi sotto di essa.

Rotazione: POST /v1/keys/{id}/rotate crea una chiave sostitutiva con lo stesso nome, ambiti, budget e limiti, restituita una sola volta. La vecchia chiave continua a funzionare per grace (predefinito 24h, da "0" a "7d"). Auto-revoca: DELETE /v1/keys/self revoca la chiave chiamante e le sue chiavi per sotto-agenti, senza bisogno di alcun ambito, così un agente che sospetta una fuga di dati può agire subito.

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

Altri dettagli su come proteggiamo chiavi e dati: sicurezza.

Crediti e approvazione#

L'uso si paga con crediti prepagati, Da $20 a $2,000 per ricarica, al massimo $2,000 ogni 24 ore e 2 link di approvazione aperti alla volta. L'agente chiede una ricarica (20 $ per impostazione predefinita) e riceve un approval_url: una pagina di finanziamento in cui la persona per cui lavora conferma o modifica l'importo, può attivare la ricarica automatica e paga con carta. I crediti arrivano una volta confermato il pagamento, e inviamo una ricevuta via email. Non viene mai addebitato nulla senza quell'approvazione. I crediti non scadono. Quando finiscono, le richieste restituiscono 402 insufficient_credits con il saldo e l'importo necessario.

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

La ricarica automatica è facoltativa e consigliata: quando il saldo scende sotto una soglia (predefinita 5 $), la carta salvata aggiunge un importo fisso (predefinito 20 $), così l'agente non si blocca mai. La persona la attiva dalla pagina di finanziamento di qualsiasi ricarica, oppure senza acquistare nulla tramite un link di configurazione della ricarica automatica (billing auto-reload setup), dove salva una carta. Le ricariche sono limitate a 2.000 $ ogni 24 ore. Attivarla o alzare un qualsiasi limite richiede una nuova approvazione; disattivarla o abbassarla no. Se una ricarica viene rifiutata, la ricarica automatica si disattiva da sola e il 402 successivo dice all'agente di ottenere un nuovo link. billing status mostra il saldo e le eventuali ricariche in sospeso; billing transactions elenca ogni acquisto, ricarica e addebito.

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

Avvisi e webhook#

Le risposte possono includere x-st-notice con codici separati da virgole: low_balance (un account con saldo inferiore a $5). Un agente che ne vede uno dovrebbe dire alla persona per cui lavora cosa approvare. GET /v1/account, account_status di MCP, status e doctor mostrano gli stessi codici con le parole da riferire.

I webhook inviano invece gli stessi segnali: balance.low, key.expiring e budget.exhausted. Gli endpoint devono essere URL https pubblici sulla porta 443. Ogni POST include x-st-signature: t=…,v1=…, un HMAC-SHA256 di <t>.<raw body> con chiave il segreto di firma dell'endpoint, mostrato una sola volta quando lo aggiungi. Le consegne vanno al tuo URL ovunque sia ospitato, anche fuori dalla regione del tuo account, e contengono solo id, type, created_at, region, account_id e data: id, importi interi in micro-dollari, conteggi di giorni e timestamp, mai prompt, nomi o email. data per 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}. Le consegne non riuscite vengono ritentate con backoff per circa due giorni.

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

Header di richiesta facoltativi: x-st-app indica il nome della tua app nei record di utilizzo (non pubblicato), e x-st-session mantiene una conversazione sulla stessa replica così il suo prefisso in cache viene riutilizzato (solo in memoria, mai conservato). In Canada le richieste non vengono mai dirottate verso un altro paese: quando tutte le repliche di un modello sono occupate, una richiesta attende brevemente, poi riceve 429 capacity_exhausted con Retry-After.

Inferenza batch#

Carica un file JSONL di richieste e ottieni i risultati al 50% del prezzo normale. I batch hanno una finestra di completamento di 24 ore e di solito terminano entro quel tempo, ma il completamento nei tempi non è garantito. Gli endpoint Files e Batches seguono quelli di OpenAI, quindi client.batches.create funziona. Ogni riga viene convalidata in anticipo, quindi un file non valido fallisce in pochi secondi.

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

Embedding#

POST /v1/embeddings con un modello di embedding (trovane uno con models --live --modality embedding). L'input può essere una stringa o un array di stringhe.

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

Fine-tuning#

Addestra un adapter LoRA sui tuoi esempi. Il risultato è un id di modello privato che solo il tuo account può chiamare, servito sulle stesse repliche del suo modello base e fatturato al prezzo per token del modello base. Si possono addestrare solo i modelli base che girano sulle nostre GPU nella tua regione, e gli adapter non si possono scaricare. L'addestramento si paga per 1M di token di addestramento (token del dataset × epoche); la risposta del job include una stima prima che parta qualsiasi cosa. Si paga con crediti prepagati. Vedi prezzi.

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

Server MCP#

MCP remoto sull'host API della tua regione: https://api.us.scaledthought.com/mcp (quello del Canada, https://api.ca.scaledthought.com/mcp, è in arrivo; Streamable HTTP, specifica 2026-07-28). Autenticati con la tua chiave API come bearer token. MCP non può creare account: registrati prima con npx -y scaledthought@0.3 init o POST /v1/accounts, poi npx -y scaledthought@0.3 mcp stampa il comando e la configurazione esatti per la tua regione. L'agente ottiene questi strumenti:

npx -y scaledthought@0.3 mcp

CLI#

Eseguila come npx -y scaledthought@0.3 <command>. L'output è JSON quando stdout non è un terminale (o con --json), e gli errori sono una riga JSON su stderr con code, message e hint. Non chiede mai input. Le chiavi arrivano da ST_API_KEY o da ./.env, mai da flag.

Riferimento API#

Limiti di frequenza#

I limiti sono per chiave. Oltre il limite, le chiamate restituiscono 429 rate_limit_exceeded con un header Retry-After in secondi. Fino al primo acquisto di crediti dell'account, le chiavi possono abbassare i propri limiti ma non alzarli.

Errori#

Gli errori API hanno la forma {"error":{"message","type","code"}}. Gli errori della CLI aggiungono un hint ed escono con un codice diverso da zero.