Commencez en un seul prompt.

Démarrage rapide#

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

Authentification#

Envoyez votre clé comme jeton bearer. Les clés sont limitées à une seule région et peuvent avoir leur propre budget. L’URL de base est l’hôte de votre région, enregistré dans .env sous ST_BASE_URL : https://api.us.scaledthought.com/v1 (celui du Canada, https://api.ca.scaledthought.com/v1, arrive bientôt).

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

Complétions de chat#

POST /v1/chat/completions accepte le format de requête d’OpenAI. Utilisez un identifiant de modèle tiré 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#

Définissez stream: true pour recevoir des événements envoyés par le serveur (server-sent events) au format delta d’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="")

Appel d’outils#

Passez tools au format d’OpenAI. Les modèles qui prennent en charge l’appel d’outils renvoient des tool_calls standard. La prise en charge et la qualité varient selon le modèle : consultez la fiche d’un modèle avant de vous y fier.

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)

Sortie structurée#

Utilisez response_format avec un schéma JSON. Sur les modèles qui le prennent en charge, la sortie est contrainte au schéma pendant le décodage. Validez le résultat avant de vous y fier.

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"],
        }},
    },
)

API Responses et Codex#

POST $ST_BASE_URL/responses parle l’API Responses d’OpenAI, donc les clients qui n’utilisent que ce protocole, comme Codex, peuvent utiliser ScaledThought comme fournisseur de modèles. Elle accepte input (une chaîne, ou des messages et des éléments function_call et function_call_output), instructions, des outils de type fonction et personnalisés (forme libre), tool_choice, max_output_tokens, text.format pour une sortie JSON et stream: true (des événements Responses, se terminant par response.completed ou response.incomplete avec son usage, ou response.failed avec une error).

Elle est sans état. Nous ne stockons aucune réponse : envoyez donc toute la conversation dans input à chaque tour (Codex le fait) et omettez previous_response_id, qui renvoie 400 invalid_request ; store vaut toujours false. Les outils hébergés comme la recherche de fichiers renvoient 400 ; un outil de recherche web est ignoré. Les requêtes sans max_output_tokens reçoivent un plafond égal à ce que le contexte du modèle laisse après votre prompt, au plus 32 768 tokens.

La facturation est la même que pour les complétions de chat : par token, d’après l’utilisation que rapporte le serveur du modèle, payée avec vos crédits.

# ~/.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 lit ST_API_KEY dans l’environnement : chargez donc d’abord ./.env dans le shell. wire_api = "responses" est obligatoire : ScaledThought sert Codex via l’API Responses.

model_catalog_url indique à Codex les fenêtres de contexte des modèles en ligne dans votre région, pour qu’il compacte les longues sessions à temps, et lui donne son outil d’édition apply_patch. Ce catalogue est construit à partir des modèles en ligne à chaque requête ; Codex l’appelle avec votre clé, gardez-le donc sur le même hôte que base_url (celui de votre région).

Modèles et benchmarks#

GET /v1/models liste les identifiants des modèles en ligne dans votre région, au format d’OpenAI. Cette liste fait foi sur ce que vous pouvez appeler. GET /v1/models/{id} renvoie le prix d’un modèle, sa longueur de contexte, sa date de sortie, ses résultats de benchmarks et son état, pour qu’un agent puisse choisir sans qu’un humain lise une page web. Pour chercher et filtrer, utilisez npx -y scaledthought@0.3 models --live ou l’outil MCP models_search. Pour les personnes, /pricing liste chaque modèle en ligne aux États-Unis avec son prix, depuis la même API.

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

Régions et conservation#

Chaque clé est liée à sa région. La région des États-Unis est ouverte maintenant ; le Canada (ca) arrive bientôt ; son API ne répond pas avant son ouverture. Les requêtes sont servies et journalisées, et les données de compte et d’utilisation stockées, uniquement dans ce pays. Les paiements par carte de toutes les régions sont traités par Stripe aux États-Unis. Les prompts et les complétions ne sont pas stockés une fois la réponse renvoyée, et ne sont jamais utilisés pour l’entraînement. Les fichiers de lots et de fine-tuning sont effacés après 30 jours, ou plus tôt avec DELETE /v1/files/{id}. Chaque réponse porte x-st-region et x-st-data-retention: none. Voir sécurité (ou /security.json) et la Politique de confidentialité (en anglais).

Clés et budgets#

Les agents peuvent créer des clés à portée limitée avec des plafonds de dépense quotidiens stricts. Quand un budget est atteint, les appels renvoient 402 au lieu de dépenser davantage. Une clé révoquée cesse de fonctionner en environ 30 secondes.

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

Les portées sont inference, read, keys, billing. Une clé ne peut donner à une nouvelle clé que des portées qu’elle possède elle-même (sinon 403 scope_not_allowed). Expiration : envoyez expires_in (comme "30d") ou expires_at, jusqu’à 365 jours ; ensuite, la clé reçoit 401 key_expired. Une clé ne survit jamais à la clé qui l’a créée.

Clés de sous-agent : avec child: true, la nouvelle clé enregistre la clé appelante comme parente. Son budget quotidien tient dans ce qu’il reste aujourd’hui à la parente, ses limites de débit et son expiration ne dépassent pas celles de la parente, et elle ne peut gérer que ses propres sous-clés. Révoquer une clé révoque toutes les clés situées sous elle.

Rotation : POST /v1/keys/{id}/rotate crée une clé de remplacement avec le même nom, les mêmes portées, le même budget et les mêmes limites, renvoyée une seule fois. L’ancienne clé continue de fonctionner pendant grace (par défaut 24h, de "0" à "7d"). Auto-révocation : DELETE /v1/keys/self révoque la clé appelante et ses clés de sous-agent, sans portée requise, pour qu’un agent qui soupçonne une fuite puisse agir immédiatement.

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

Plus de détails sur la protection des clés et des données : sécurité.

Crédits et approbation#

L’utilisation est payée avec des crédits prépayés, de $20 à $2,000 par recharge, au plus $2,000 par 24 heures et 2 liens d’approbation ouverts à la fois. L’agent demande une recharge (20 $ par défaut) et reçoit une approval_url : une page de financement où la personne pour qui il travaille confirme ou modifie le montant, peut activer la recharge automatique, et paie par carte. Les crédits arrivent une fois le paiement confirmé, et nous envoyons un reçu par courriel. Rien n’est jamais facturé sans cette approbation. Les crédits n’expirent pas. Quand ils sont épuisés, les requêtes renvoient 402 insufficient_credits avec le solde et le montant nécessaire.

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

La recharge automatique est facultative et recommandée : quand le solde passe sous un seuil (5 $ par défaut), la carte enregistrée ajoute un montant fixe (20 $ par défaut), pour que l’agent ne soit jamais bloqué. La personne pour qui l’agent travaille l’active sur la page de financement de n’importe quelle recharge, ou sans rien acheter via un lien de configuration de la recharge automatique (billing auto-reload setup), où elle enregistre une carte. Les recharges sont limitées à 2 000 $ par 24 heures. L’activer ou relever une limite exige une nouvelle approbation ; la désactiver ou la réduire, non. Si une recharge est refusée, la recharge automatique se désactive d’elle-même et la prochaine erreur 402 indique à l’agent d’obtenir un nouveau lien. billing status affiche le solde et les recharges en attente ; billing transactions liste chaque achat, recharge et débit.

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

Avis et webhooks#

Les réponses peuvent porter x-st-notice avec des codes séparés par des virgules : low_balance (un compte dont le solde est inférieur à $5). Un agent qui en voit un doit dire à la personne pour qui il travaille ce qu’il faut approuver. GET /v1/account, l’outil MCP account_status, status et doctor affichent les mêmes codes avec le texte à transmettre.

Les webhooks poussent plutôt les mêmes signaux : balance.low, key.expiring et budget.exhausted. Les points de terminaison doivent être des URL https publiques sur le port 443. Chaque POST porte x-st-signature: t=…,v1=…, un HMAC-SHA256 de <t>.<raw body> calculé avec le secret de signature du point de terminaison, affiché une seule fois quand vous l’ajoutez. Les envois vont à votre URL où qu’elle soit hébergée, même hors de la région de votre compte, et ne portent que id, type, created_at, region, account_id et data : des identifiants, des montants entiers en micro-dollars, des nombres de jours et des horodatages, jamais de prompts, de noms ni d’adresses courriel. data par événement : balance.low {balance_micros, threshold_micros}, key.expiring {key_id, expires_at}, budget.exhausted {scope, key_id, budget_micros, spent_today_micros, resets_at}. Les envois qui échouent sont relancés avec un délai croissant pendant environ deux jours.

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

En-têtes de requête facultatifs : x-st-app nomme votre application dans les données d’utilisation (non publié), et x-st-session garde une conversation sur la même réplique pour que son préfixe en cache soit réutilisé (en mémoire seulement, jamais stocké). Au Canada, les requêtes ne débordent jamais vers un autre pays : quand toutes les répliques d’un modèle sont occupées, une requête attend brièvement, puis reçoit 429 capacity_exhausted avec Retry-After.

Inférence par lots#

Téléversez un fichier JSONL de requêtes et obtenez les résultats à 50 % du prix normal. Les lots s’exécutent dans une fenêtre de traitement de 24 heures et se terminent généralement dans ce délai, mais ce n’est pas garanti. Les points de terminaison Files et Batches suivent ceux d’OpenAI, donc client.batches.create fonctionne. Chaque ligne est validée dès le départ : un fichier invalide échoue en quelques secondes.

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 avec un modèle d’embeddings (trouvez-en un avec models --live --modality embedding). L’entrée peut être une chaîne ou un tableau de chaînes.

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

Fine-tuning#

Entraînez un adaptateur LoRA sur vos propres exemples. Le résultat est un identifiant de modèle privé que seul votre compte peut appeler, servi sur les mêmes répliques que son modèle de base et facturé au prix par token du modèle de base. Seuls les modèles de base exécutés sur nos propres GPU dans votre région peuvent être entraînés, et les adaptateurs ne peuvent pas être téléchargés. L’entraînement est facturé par 1 M de tokens d’entraînement (tokens du jeu de données × époques) ; la réponse de la tâche inclut une estimation avant tout lancement. Payé avec des crédits prépayés. Voir les tarifs.

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

Serveur MCP#

MCP distant sur l’hôte d’API de votre région : https://api.us.scaledthought.com/mcp (celui du Canada, https://api.ca.scaledthought.com/mcp, arrive bientôt ; Streamable HTTP, spécification 2026-07-28). Authentifiez-vous avec votre clé d’API comme jeton bearer. MCP ne peut pas créer de compte : inscrivez-vous d’abord avec npx -y scaledthought@0.3 init ou POST /v1/accounts, puis npx -y scaledthought@0.3 mcp affiche la commande et la configuration exactes pour votre région. L’agent dispose de ces outils :

npx -y scaledthought@0.3 mcp

CLI#

Exécutez-la sous la forme npx -y scaledthought@0.3 <command>. La sortie est en JSON chaque fois que stdout n’est pas un terminal (ou avec --json), et les erreurs sont une ligne JSON sur stderr avec code, message et hint. Rien n’est demandé de façon interactive. Les clés viennent de ST_API_KEY ou de ./.env, jamais d’options de ligne de commande.

Référence de l’API#

Limites de débit#

Les limites s’appliquent par clé. Au-delà de la limite, les appels renvoient 429 rate_limit_exceeded avec un en-tête Retry-After en secondes. Jusqu’au premier achat de crédits du compte, les clés peuvent abaisser leurs limites mais pas les relever.

Erreurs#

Les erreurs de l’API sont de la forme {"error":{"message","type","code"}}. Les erreurs de la CLI ajoutent un hint et se terminent avec un code non nul.