API para desarrolladores (/v1)

El gateway de Theus expone una API compatible con el estándar OpenAI en https://api.theus.pe/v1. Con una sola API key de Theus accedes a las rutas habilitadas para tu plan y a TITAN, sin gestionar keys de ningún proveedor.

Base y autenticación

Base URL:  https://api.theus.pe/v1

https://theus.pe/v1 sigue funcionando como alias de compatibilidad permanente; para integraciones nuevas usa siempre el subdominio api.theus.pe.

Crea tu API key desde el dashboard de tu cuenta en theus.pe. El gateway acepta la key de dos formas equivalentes:

# Bearer (recomendado, estilo OpenAI)
Authorization: Bearer theus_mlp_...

# o como header propio
x-api-key: theus_mlp_...

POST /v1/chat/completions

Inferencia de chat, compatible OpenAI. Usa cualquier id del catálogo como model — incluido titan, el orquestador. La respuesta nunca expone el modelo upstream: model devuelve el id Theus que pediste.

curl https://api.theus.pe/v1/chat/completions \
  -H "Authorization: Bearer $THEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "titan",
    "messages": [
      {"role": "system", "content": "Eres un asistente de código conciso."},
      {"role": "user", "content": "Escribe una función en Python que valide un RUC peruano."}
    ],
    "max_tokens": 800,
    "stream": false
  }'

Respuesta (formato chat.completion estándar):

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "titan",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "…"}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": …, "completion_tokens": …, "total_tokens": …}
}

Streaming (SSE)

Con "stream": true la respuesta llega como text/event-stream: chunks chat.completion.chunk con deltas, un chunk final con usage y el terminador data: [DONE]. El gateway pide usage al upstream automáticamente (stream_options.include_usage) para facturar con datos reales; el chunk final extra con choices vacíos es estándar e inocuo.

curl -N https://api.theus.pe/v1/chat/completions \
  -H "Authorization: Bearer $THEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "titan", "messages": [{"role": "user", "content": "Hola"}], "stream": true}'

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"delta":{"content":"…"}}], …}
…
data: [DONE]

TITAN Fleet Scheduler v1

El control-plane distribuido de TITAN vive en el mismo Gateway. Una corrida crea un DAG durable; los workers oficiales de CLI, Chat y Enterprise reclaman jobs mediante leases exclusivos, mantienen heartbeats y confirman el resultado con fencing e idempotencia. Estas rutas son para runtimes Theus, no para simular trabajo desde un cliente ordinario.

POST /v1/embeddings

Embeddings compatibles OpenAI, con el alias del catálogo theus-embed (la memoria semántica del CLI). input acepta un string no vacío o una lista. Passthrough de parámetros estándar: encoding_format, dimensions, user.

curl https://api.theus.pe/v1/embeddings \
  -H "Authorization: Bearer $THEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "theus-embed",
    "input": ["función que valida el token de sesión", "handler de pagos"]
  }'

La respuesta es el objeto list de embeddings estándar, con model enmascarado al id Theus. El consumo entra al mismo ledger de tokens que el chat.

POST /v1/images/generations

Generación de imágenes, compatible OpenAI, con los modelos de imagen del catálogo: theus-image-flash (por defecto), theus-image-mini y theus-image-pro. Requiere capacidad de imagen disponible en tu cuenta, según el plan vigente o los paquetes contratados. La imagen vuelve en la respuesta como b64_json (base64); el gateway no devuelve URLs upstream.

curl https://api.theus.pe/v1/images/generations \
  -H "Authorization: Bearer $THEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "theus-image-flash",
    "prompt": "logo minimalista de una forja, fondo oscuro, trazo dorado",
    "size": "1024x1024"
  }'

Respuesta:

{
  "created": 1767…,
  "data": [
    {"b64_json": "iVBORw0KGgo…"}
  ],
  "usage": {…}
}

Editar una imagen

Pasando input_references el modelo transforma las imágenes que le das en vez de crear desde cero: retocar, recolorear, sustituir el fondo o combinar varias. El prompt describe el cambio, no la escena completa.

A diferencia de imagen → video, aquí la imagen puede ir embebida como data URL en base64, además de como enlace: no hace falta publicarla en ningún sitio.

curl https://api.theus.pe/v1/images/generations \
  -H "Authorization: Bearer $THEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "theus-image-flash",
    "prompt": "cambia el fondo a un degradado oscuro y conserva el trazo dorado",
    "input_references": [
      {
        "type": "image_url",
        "image_url": {"url": "data:image/png;base64,iVBORw0KGgo…"}
      }
    ]
  }'

Cuántas imágenes de partida admite cada modelo: theus-image-flash y theus-image-pro hasta 14; theus-image-mini hasta 16. Editar consume el cubo de imagen igual que generar: una imagen entregada, un cargo.

POST /v1/media/uploads

Publica una imagen con una URL temporal. Existe para imagen → video: el proveedor de video descarga el primer fotograma por HTTP, así que una imagen de tu disco le resulta invisible.

curl https://api.theus.pe/v1/media/uploads \
  -H "Authorization: Bearer $THEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data_b64": "iVBORw0KGgo…"}'

{
  "url": "https://api.theus.pe/v1/media/in/AbC…xyz.png",
  "expires_at": 1767…,
  "bytes": 48213
}

La URL devuelta es pública (sin cabecera de autorización, porque quien la descarga es la infraestructura del proveedor), tiene un identificador inadivinable y caduca a las 2 horas. Se admiten PNG, JPEG, GIF y WebP hasta 8 MB; el tipo se determina por la firma real del archivo, no por lo que declares. Hay un tope de imágenes vivas por cuenta: no es un alojamiento permanente.

POST /v1/chat/blobs

Sube un adjunto (imagen o documento) al almacén privado de tu cuenta y devuelve solo una referencia: el binario jamás entra en la conversación ni viaja al modelo en bruto. Es lo que usa el chat web cuando arrastras un archivo.

curl https://api.theus.pe/v1/chat/blobs \
  -H "Authorization: Bearer $THEUS_API_KEY" \
  -F "file=@informe.pdf"

{
  "id": "9f3c…",
  "mime": "application/pdf",
  "bytes": 24117248,
  "extracto_b64": "RUwgcHJveWVjdG8…",
  "extracto_chars": 32768,
  "truncado": true
}

Límites: 30 MB por archivo, 300 MB de archivos vivos por cuenta y 50 archivos. El tipo se determina por la firma real, no por lo que declares; los ejecutables y los SVG se rechazan. De un PDF con capa de texto se extraen hasta 400 páginas y 128 KB de texto (truncado: true te avisa si se cortó); un PDF escaneado se guarda como adjunto descargable, sin extracto — se te dice, no se finge.

POST /v1/videos

Video con los modelos del catálogo: theus-video (por defecto), theus-video-plus, theus-video-max y theus-video-ultra. Requiere capacidad de video disponible en tu cuenta según las condiciones del servicio o los paquetes contratados. La generación es asíncrona: crear el clip devuelve un job con id y status, que luego consultas y descargas.

curl https://api.theus.pe/v1/videos \
  -H "Authorization: Bearer $THEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "theus-video",
    "prompt": "un colibrí en cámara lenta sobre flores andinas",
    "seconds": 8
  }'

Respuesta (job de video):

{
  "id": "video_…",
  "object": "video",
  "model": "theus-video",
  "status": "queued",
  "progress": 0
}

Cada modelo admite un conjunto propio de duraciones: theus-video de 4 a 12 s, theus-video-plus 5 o 10 s, theus-video-max 6 o 10 s y theus-video-ultra 4, 6 u 8 s. Pedir una duración que el modelo no admite devuelve un error del proveedor.

Imagen → video

Pasando frame_images el modelo anima una imagen en vez de partir de cero, usándola como primer fotograma. La imagen debe ser una URL pública: el proveedor la descarga (usa /v1/media/uploads si la tienes en local).

curl https://api.theus.pe/v1/videos \
  -H "Authorization: Bearer $THEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "theus-video",
    "prompt": "que el colibrí despegue lentamente",
    "seconds": 6,
    "frame_images": [
      {
        "type": "image_url",
        "image_url": {"url": "https://api.theus.pe/v1/media/in/AbC…xyz.png"},
        "frame_type": "first_frame"
      }
    ]
  }'

Los cuatro modelos aceptan first_frame; theus-video y theus-video-ultra aceptan además last_frame para interpolar entre dos imágenes.

GET /v1/videos/{id} — estado del job

curl https://api.theus.pe/v1/videos/video_… \
  -H "Authorization: Bearer $THEUS_API_KEY"

Devuelve el mismo objeto video con status (queued → in_progress → completed | failed) y progress. Sondea hasta completed.

GET /v1/videos/{id}/content — descargar el clip

curl -o clip.mp4 https://api.theus.pe/v1/videos/video_…/content \
  -H "Authorization: Bearer $THEUS_API_KEY"

GET /v1/models

Catálogo servible en formato lista OpenAI. Solo aparecen los modelos que hoy resuelven a un proveedor operativo; cada entrada añade name, modality, tier y status, más available (si tu plan alcanza ese modelo) y required_plan cuando no lo alcanza.

curl https://api.theus.pe/v1/models \
  -H "Authorization: Bearer $THEUS_API_KEY"

El bloque routing

Si vas a elegir el modelo desde tu cliente, cada entrada puede traer un bloque routing con lo necesario para decidir:

{
  "id": "claude-opus-4-8",
  "name": "Claude Opus 4.8",
  "modality": "codigo",
  "available": true,
  "routing": {
    "weight": 5.0,
    "tools": true,
    "vision": true,
    "context_window": 200000,
    "max_output_tokens": 32000,
    "quality_tier": 4,
    "task_affinity": ["code", "tool_use"],
    "quarantined": false,
    "eligible": true
  }
}

POST /v1/responses

Compatibilidad básica con el API Responses: acepta input como texto o lista de mensajes {role, content}, más max_output_tokens, temperature y top_p, y responde un objeto response con output_text. El streaming de Responses no está implementado (501): para streaming usa /v1/chat/completions con stream: true.

Errores

Los errores del gateway usan el formato OpenAI:

{
  "error": {
    "message": "Alcanzaste el limite de solicitudes por minuto del plan Theus Pro. Reintenta en 12 segundos.",
    "type": "theus_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

Rate limits y cuotas

El servicio aplica límites de solicitudes y capacidad según el plan. La oferta vigente usa ventanas de cinco horas y siete días, compartidas entre las superficies de Theus; no es una bolsa mensual de tareas. Consulta Planes, Consumo y el estado de tu cuenta.

Los rechazos por límite conservan un código y motivo consultables; cuando corresponde, Retry-After indica la espera. El servicio no inicia compras de recargas automáticamente. El potenciador requiere activación y saldo disponible.

El uso se contabiliza con el usage reportado cuando existe; si falta, el servicio usa una estimación conservadora. Entrada y salida tienen pesos propios. Una ruta anunciada por GET /v1/models no garantiza que sea elegible para cualquier petición: se aplican también modalidad, capacidades, contexto y disponibilidad.