API para desarrolladores (/v1)

El gateway de Theus expone una API compatible con el estándar OpenAI en https://theus.pe/v1. Con una sola API key de Theus accedes a todo el catálogo de modelos y a TITAN, sin gestionar keys de ningún proveedor.

Base y autenticación

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

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://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://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]

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://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 el modelo del catálogo gpt-image-1 (plan Studio AI o superior). La imagen vuelve en la respuesta como b64_json (base64); el gateway no devuelve URLs upstream.

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

Respuesta:

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

POST /v1/videos

Texto a video (clips cortos) con el modelo del catálogo sora-2 (plan Studio AI o superior). La generación es asíncrona: crear el clip devuelve un job con id y status, que luego consultas y descargas.

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

Respuesta (job de video):

{
  "id": "video_…",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "seconds": "8"
}

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

curl https://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://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.

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

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 Pro Code. Reintenta en 12 segundos.",
    "type": "theus_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

Rate limits y cuotas

Cada plan define solicitudes por minuto (por API key) y tokens incluidos por periodo. Ambos límites responden 429 con header Retry-After.