Empieza con un solo prompt.

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

Autenticación#

Envía tu clave como token bearer. Las claves están limitadas a una región y pueden tener su propio presupuesto. La URL base es el host de tu región, guardado en .env como ST_BASE_URL: https://api.us.scaledthought.com/v1 (https://api.ca.scaledthought.com/v1, la de Canadá, estará disponible próximamente).

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

Chat completions#

POST /v1/chat/completions acepta el formato de solicitud de OpenAI. Usa un id de modelo de npx -y scaledthought@0.3 models --live o 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#

Define stream: true para recibir server-sent events en el formato delta de 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="")

Llamadas a herramientas#

Pasa tools en el formato de OpenAI. Los modelos que admiten llamadas a herramientas devuelven tool_calls estándar. El soporte y la calidad varían según el modelo, así que revisa la ficha del modelo antes de depender de ello.

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)

Salida estructurada#

Usa response_format con un JSON schema. En los modelos que lo admiten, la salida se restringe al schema durante la decodificación. Valida el resultado antes de depender de él.

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

POST $ST_BASE_URL/responses habla la Responses API de OpenAI, así que los clientes que solo usan ese protocolo, como Codex, pueden usar ScaledThought como proveedor de modelos. Acepta input (una cadena, o mensajes y elementos function_call y function_call_output), instructions, herramientas de función y personalizadas (formato libre), tool_choice, max_output_tokens, text.format para salida JSON y stream: true (eventos de Responses, que terminan con response.completed o response.incomplete con su usage, o con response.failed con un error).

No tiene estado. No almacenamos respuestas, así que envía la conversación completa en input en cada turno (Codex lo hace) y omite previous_response_id, que devuelve 400 invalid_request; store siempre es false. Las herramientas alojadas, como la búsqueda de archivos, devuelven 400; una herramienta de búsqueda web se ignora. Las solicitudes sin max_output_tokens reciben como tope lo que el contexto del modelo deja libre después de tu prompt, como máximo 32,768 tokens.

La facturación es la misma que en chat completions: por token, según el uso que informa el servidor del modelo, pagada con tus 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

Codex lee ST_API_KEY del entorno, así que primero carga ./.env en la shell. wire_api = "responses" es obligatorio: ScaledThought sirve a Codex mediante la Responses API.

model_catalog_url le indica a Codex las ventanas de contexto de los modelos disponibles en tu región, para que compacte las sesiones largas a tiempo, y le da su herramienta de edición apply_patch. Se genera a partir de los modelos disponibles en cada solicitud; Codex envía tu clave con ella, así que mantenla en el mismo host que base_url (el de tu región).

Modelos y benchmarks#

GET /v1/models lista los ids de los modelos disponibles en tu región, en el formato de OpenAI. Esa lista es la referencia de lo que puedes llamar. GET /v1/models/{id} devuelve el precio, la longitud de contexto, la fecha de lanzamiento, los resultados de benchmarks y el estado de un modelo, para que un agente pueda elegir sin que una persona lea una página web. Para buscar y filtrar, usa npx -y scaledthought@0.3 models --live o la herramienta MCP models_search. Para las personas, /pricing lista cada modelo disponible en EE. UU. con su precio, desde la misma API.

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

Regiones y retención#

Cada clave está vinculada a su región. La región de EE. UU. está abierta ahora; Canadá (ca) estará disponible próximamente; su API no responde hasta que abra. Las solicitudes se atienden y se registran, y los registros de cuenta y de uso se almacenan, solo en ese país. Los pagos con tarjeta de todas las regiones los procesa Stripe en EE. UU. Los prompts y las completions no se almacenan después de devolver la respuesta y nunca se usan para entrenar. Los archivos de lotes y de ajuste fino se borran después de 30 días, o antes con DELETE /v1/files/{id}. Cada respuesta lleva x-st-region y x-st-data-retention: none. Consulta seguridad (o /security.json) y la Política de privacidad (en inglés).

Claves y presupuestos#

Los agentes pueden crear claves con alcances limitados y límites de gasto diario estrictos. Cuando se alcanza un presupuesto, las llamadas devuelven 402 en lugar de gastar más. Una clave revocada deja de funcionar en unos 30 segundos.

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

Alcances: son inference, read, keys, billing. Una clave solo puede dar a una clave nueva los alcances que ella misma tiene (si no, 403 scope_not_allowed). Vencimiento: envía expires_in (como "30d") o expires_at, hasta 365 días; después, la clave recibe 401 key_expired. Una clave nunca dura más que la clave que la creó.

Claves de subagente: con child: true, la clave nueva registra a la clave que la llama como su clave madre. Su presupuesto diario cabe en lo que le queda hoy a la clave madre, sus límites de tasa y su vencimiento no superan los de la madre, y solo puede gestionar sus propias subclaves. Revocar una clave revoca todas las claves que dependen de ella.

Rotación: POST /v1/keys/{id}/rotate crea una clave de reemplazo con el mismo nombre, alcances, presupuesto y límites, que se devuelve una sola vez. La clave anterior sigue funcionando durante grace (por defecto 24h, de "0" a "7d"). Autorrevocación: DELETE /v1/keys/self revoca la clave que hace la llamada y sus claves de subagente, sin necesidad de ningún alcance, para que un agente que sospecha una filtración pueda actuar de inmediato.

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

Más sobre cómo se protegen las claves y los datos: seguridad.

Créditos y aprobación#

El uso se paga con créditos prepagados, de $20 a $2,000 por recarga, como máximo $2,000 cada 24 horas y 2 enlaces de aprobación abiertos a la vez. El agente solicita una recarga ($20 por defecto) y recibe un approval_url: una página de fondeo donde la persona a cargo confirma o cambia el monto, puede activar la recarga automática y paga con tarjeta. Los créditos llegan una vez confirmado el pago, y enviamos un recibo por correo. Nunca se cobra nada sin esa aprobación. Los créditos no vencen. Cuando se acaban, las solicitudes devuelven 402 insufficient_credits con el saldo y el monto necesario.

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

La recarga automática es opcional y recomendada: cuando el saldo baja de un umbral (por defecto $5), la tarjeta guardada agrega un monto fijo (por defecto $20), para que el agente nunca se detenga. La persona a cargo la activa en la página de fondeo de cualquier recarga, o sin comprar nada mediante un enlace de configuración de recarga automática (billing auto-reload setup), donde guarda una tarjeta. Las cargas están limitadas a $2,000 cada 24 horas. Activarla o subir cualquier límite requiere una nueva aprobación; desactivarla o reducirla, no. Si se rechaza una recarga, la recarga automática se desactiva sola y el siguiente 402 le indica al agente que obtenga un enlace nuevo. billing status muestra el saldo y las recargas pendientes; billing transactions lista cada compra, recarga y cargo.

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 y webhooks#

Las respuestas pueden llevar x-st-notice con códigos separados por comas: low_balance (una cuenta cuyo saldo es menor a $5). Un agente que vea uno debería decirle a la persona a cargo qué aprobar. GET /v1/account, MCP account_status, status y doctor muestran los mismos códigos con el texto que hay que transmitir.

Los webhooks envían las mismas señales de forma activa: balance.low, key.expiring y budget.exhausted. Los endpoints deben ser URL https públicas en el puerto 443. Cada POST lleva x-st-signature: t=…,v1=…, un HMAC-SHA256 de <t>.<raw body> con la clave secreta de firma del endpoint, que se muestra una sola vez cuando lo agregas. Las entregas van a tu URL dondequiera que esté alojada, incluso fuera de la región de tu cuenta, y solo llevan id, type, created_at, region, account_id y data: ids, montos enteros en micro-dólares, cantidades de días y marcas de tiempo, nunca prompts, nombres ni correos. 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}. Las entregas fallidas se reintentan con backoff durante unos dos días.

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

Encabezados de solicitud opcionales: x-st-app nombra tu app en los registros de uso (no se publica), y x-st-session mantiene una conversación en la misma réplica para reutilizar su prefijo en caché (solo en memoria, nunca se almacena). En Canadá, las solicitudes nunca se desvían a otro país: cuando todas las réplicas de un modelo están ocupadas, una solicitud espera brevemente y luego recibe 429 capacity_exhausted con Retry-After.

Inferencia por lotes#

Sube un archivo JSONL de solicitudes y obtén resultados al 50% del precio normal. Los lotes se ejecutan en una ventana de finalización de 24 horas y por lo general terminan dentro de ella, pero no se garantiza que terminen a tiempo. Los endpoints de Files y Batches siguen los de OpenAI, así que client.batches.create funciona. Cada línea se valida desde el inicio, así que un archivo con errores falla en 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 con un modelo de embeddings (encuentra uno con models --live --modality embedding). La entrada puede ser una cadena o un arreglo de cadenas.

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

Ajuste fino#

Entrena un adaptador LoRA con tus propios ejemplos. El resultado es un id de modelo privado que solo tu cuenta puede llamar, servido en las mismas réplicas que su modelo base y cobrado al precio por token del modelo base. Solo se pueden entrenar modelos base que se ejecutan en nuestras propias GPU en tu región, y los adaptadores no se pueden descargar. El entrenamiento se cobra por cada 1M de tokens de entrenamiento (tokens del dataset × épocas); la respuesta del trabajo incluye una estimación antes de que se ejecute nada. Se paga con créditos prepagados. Consulta precios.

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 en el host de la API de tu región: https://api.us.scaledthought.com/mcp (https://api.ca.scaledthought.com/mcp, el de Canadá, estará disponible próximamente; Streamable HTTP, especificación 2026-07-28). Autentícate con tu clave de API como token bearer. MCP no puede crear cuentas: regístrate primero con npx -y scaledthought@0.3 init o POST /v1/accounts, y luego npx -y scaledthought@0.3 mcp muestra el comando y la configuración exactos para tu región. El agente obtiene estas herramientas:

npx -y scaledthought@0.3 mcp

CLI#

Ejecútala como npx -y scaledthought@0.3 <command>. La salida es JSON siempre que stdout no sea una terminal (o con --json), y los errores son una línea JSON en stderr con code, message y hint. Nunca pide datos de forma interactiva. Las claves se leen de ST_API_KEY o ./.env, nunca de flags.

Referencia de la API#

Límites de tasa#

Los límites son por clave. Al superar el límite, las llamadas devuelven 429 rate_limit_exceeded con un encabezado Retry-After en segundos. Hasta la primera compra de créditos de la cuenta, las claves pueden bajar sus límites pero no subirlos.

Errores#

Los errores de la API son {"error":{"message","type","code"}}. Los errores de la CLI agregan un hint y terminan con un código distinto de cero.