Documentación

Autenticación

Tu clave está en Claves de API. Se envía en la cabecera Authorization. Exporta el par que corresponda a tu SDK: son las variables que cada librería lee sola, así que el cliente se construye sin argumentos.

# OpenAI
export OPENAI_BASE_URL=https://ai.kostra.cloud/v1
export OPENAI_API_KEY=sk-...

# Anthropic — la misma clave (sin /v1: el SDK lo agrega solo)
export ANTHROPIC_BASE_URL=https://ai.kostra.cloud
export ANTHROPIC_API_KEY=sk-...

Trata la clave como una contraseña: quien la tenga gasta tu saldo. No la publiques en un repositorio ni la incluyas en código que corra en el navegador — cualquiera puede leerla ahí.

Modelos disponibles

Usa el identificador de la primera columna en el campo model. Tu clave solo puede llamar a estos.

Contexto máx. es el tamaño mayor de prompt (todo lo que envías: sistema, historial, herramientas y adjuntos) que el proveedor acepta para ese modelo. Una petición más larga se rechaza completa —no se recorta— y no descuenta saldo. Si usas una herramienta agéntica (Claude Code, OpenCode, Cursor…), configura su límite de contexto para este modelo por debajo de esa cifra: así compacta la conversación a tiempo en vez de reintentar la misma petición rechazada.

También puedes pedir la lista desde la API: GET https://ai.kostra.cloud/v1/models.

Tu primer llamado

curl https://ai.kostra.cloud/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Hola, ¿cómo estás?"}]
  }'

Python

Con OPENAI_BASE_URL y OPENAI_API_KEY exportadas, el cliente no necesita argumentos.

pip install openai

from openai import OpenAI

client = OpenAI()

respuesta = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hola, ¿cómo estás?"}],
)

print(respuesta.choices[0].message.content)

Node.js

npm install openai

import OpenAI from "openai";

const client = new OpenAI();

const respuesta = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "Hola, ¿cómo estás?" }],
});

console.log(respuesta.choices[0].message.content);

Failover opcional

Si prefieres disponibilidad por sobre un modelo exacto, agrega fallbacks a tu solicitud: cuando el modelo primario falla, la misma solicitud se reintenta automáticamente con el siguiente de tu lista y recibes esa respuesta en lugar del error. Es opcional por solicitud — sin el campo, tu solicitud va solo al modelo que pediste, siempre.

curl https://ai.kostra.cloud/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "fallbacks": ["deepseek-v4-flash"],
    "messages": [{"role": "user", "content": "Hola"}]
  }'

Dos cosas importantes. El campo model de la respuesta siempre indica qué modelo respondió realmente. Y el cobro corresponde al modelo que respondió, a su precio publicado — si el fallback es más caro que el primario, esa solicitud cuesta la tarifa del fallback.

Formato Anthropic

Si tu código usa el SDK de Anthropic, apunta la URL base a Kostra y usa el mismo modelo. Nada más cambia: mismo saldo, misma clave.

export ANTHROPIC_BASE_URL=https://ai.kostra.cloud   # sin /v1: el SDK lo agrega solo
export ANTHROPIC_API_KEY=$OPENAI_API_KEY   # es la misma clave

from anthropic import Anthropic

client = Anthropic()

respuesta = client.messages.create(
    model="deepseek-v4-flash",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hola, ¿cómo estás?"}],
)

print(respuesta.content[0].text)

Funciona igual con curl, streaming y tools (llamada a funciones). El campo system va aparte de messages, como en la API de Anthropic.

Claude Code

Claude Code habla el formato Anthropic, así que también corre sobre Kostra. Fija cuatro variables de entorno: la URL base sin /v1, tu clave en ANTHROPIC_AUTH_TOKEN —la variable que Claude Code reserva para pasarelas como Kostra; no uses ANTHROPIC_API_KEY, que es para la API directa de Anthropic y te pedirá aprobar la clave— y el modelo, dos veces: el principal y el rápido que Claude Code usa para tareas de fondo. Sin el segundo intentará llamar a un modelo claude-* que tu clave no alcanza.

# macOS / Linux
export ANTHROPIC_BASE_URL=https://ai.kostra.cloud
export ANTHROPIC_AUTH_TOKEN=sk-...
export ANTHROPIC_MODEL=deepseek-v4-flash
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-v4-flash
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=1044480

Claude Code no conoce el tamaño de contexto de estos modelos y asume el de Claude (200K), así que compacta la conversación después del límite real y la petición se rechaza una y otra vez. Declara el contexto real con CLAUDE_CODE_MAX_CONTEXT_TOKENS (en tokens, el valor de la columna Contexto máx. del modelo que uses, sin puntos: 131072, no 131.072); Claude Code compacta solo por debajo de esa cifra. Ojo: Claude Code ignora esa variable cuando el identificador del modelo empieza por claude- —para esos modelos ya asume el contexto correcto. Si quieres compactar antes aún, CLAUDE_CODE_AUTO_COMPACT_WINDOW fija el umbral (un entero entre 100000 y el contexto del modelo), y /compact lo hace a mano.

Si Claude Code responde “There's an issue with the selected model… it may not exist or you may not have access”, casi siempre es la URL base con /v1 al final: la petición sale a /v1/v1/messages y responde 404. Quita el sufijo y abre una terminal nueva.

En Windows

En Windows las variables se guardan con setx desde el Símbolo del sistema (cmd). Quedan permanentes para tu usuario, pero solo las ve una terminal abierta después: cierra la ventana y abre una nueva antes de correr claude.

:: Símbolo del sistema (cmd)
setx ANTHROPIC_BASE_URL "https://ai.kostra.cloud"
setx ANTHROPIC_AUTH_TOKEN "sk-..."
setx ANTHROPIC_MODEL "deepseek-v4-flash"
setx ANTHROPIC_SMALL_FAST_MODEL "deepseek-v4-flash"
setx CLAUDE_CODE_MAX_CONTEXT_TOKENS "1044480"

Para comprobar que quedaron bien, en una terminal nueva:

echo %ANTHROPIC_BASE_URL%
:: debe mostrar https://ai.kostra.cloud  (sin /v1)
echo %ANTHROPIC_MODEL%

En PowerShell la sintaxis es [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://ai.kostra.cloud", "User") para cada variable, y la misma regla: abre una terminal nueva.

Caché de prompts

Si repites el mismo prefijo entre llamados —un system prompt largo, un documento de contexto— el proveedor puede servirlo desde caché. Lo informa en usage como cache_read_input_tokens y Kostra lo registra por mensaje.

Cuando el modelo tiene una tarifa de caché configurada, esos tokens se cobran a esa tarifa. Si no la tiene, se cobran como entrada normal: nunca se cobran de más por estar en caché.

Streaming

Agrega stream: true para recibir la respuesta token a token, como en el chat web.

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Cuenta hasta cinco"}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Saldo y consumo

Es el mismo saldo del chat web: no hay una bolsa aparte para la API. Cada llamado descuenta según los tokens de entrada y de salida, al precio del modelo que usaste.

Cuando el saldo llega a cero la clave deja de responder. No hay cobro automático ni deuda: recargas en Recargar y la clave vuelve a funcionar sola, sin generar una nueva.

El consumo detallado está en Mi saldo.

Errores

Compatibilidad

Están disponibles /chat/completions y /models, con los parámetros habituales: temperature, max_tokens, top_p, stop y stream.

No todos los modelos aceptan las mismas extensiones — tools y las respuestas en formato JSON dependen del proveedor. Si un parámetro no es compatible, el modelo lo ignora o responde con un error del proveedor.

¿No programas?

Puedes usar exactamente los mismos modelos desde el chat web, con el mismo saldo y sin escribir una línea de código.

También puedes conectar tus propios sistemas —cluster, repositorio, base de datos, servidor— y consultarlos con IA en modo de solo lectura: Mis herramientas.