API para desarrolladores

Tus scripts, nuestros modelos.

Una clave, un endpoint compatible con los clientes de OpenAI existentes y tu saldo de Vena Tokens como única unidad de facturación. Incluida en los planes Pro y Expert.

En tres minutos

Lo que debes saber antes de escribir una línea.

Necesitas un plan Pro o Expert
La clave está incluida a partir del plan Pro. Una cuenta gratuita o Starter recibe 403 PREMIUM_REQUIRED, tanto al crear la clave como al realizar una llamada.
Las llamadas debitan TU monedero
Cada llamada consume Vena Tokens del saldo del propietario de la clave, con los mismos multiplicadores que el chat. Nada se factura por separado.
El secreto solo se muestra una vez
Solo guardamos su huella digital: técnicamente nos resulta imposible volvértela a mostrar. Si pierdes una clave, se reemplaza mediante una rotación.
Una clave expuesta está delimitada, no es ilimitada
Límite de velocidad por clave, disyuntor por volumen y por gasto. Más allá, la clave se desactiva sola y recibes un correo electrónico.
Autenticación

Un encabezado, y nada más.

La clave se envía en la cabecera HTTP Authorization, esquema Bearer. No se acepta ningún otro canal.

Ejemplo de cabecera
Authorization: Bearer vena_sk_VOTRE_CLE

Cuatro reglas, todas ellas sobre seguridad

  • Nunca en una URL. Un parámetro de consulta acaba en los registros de acceso del servidor, en los del proxy, en la cabecera Referer y en el historial del navegador. Rechazamos rotundamente este modo de autenticación: responde 401.
  • Nunca en JavaScript de navegador. La API no publica ninguna configuración CORS, precisamente para evitar este uso: una clave en una página web es una clave publicada.
  • Una clave por entorno. 5 claves activas por cuenta: suficiente para separar producción, entorno de pruebas y puesto de desarrollo, y desactivar una sin desactivar las demás.
  • La revocación es inmediata. Surte efecto en la siguiente llamada, sin retraso de propagación ni caché.
Endpoints

Dos rutas, y eso es todo.

URL basehttps://ia.venalabs.com/api/ai/v1
Endpoints
MétodoRutaPropósitoÁmbito requerido
GET/api/ai/v1/modelsEl catálogo de modelos, con la clase, el multiplicador y los pesos aplicados. No cuesta nada: esta es la ruta que se utiliza para estimar antes de llamar.MODELS
POST/api/ai/v1/chat/completionsUna completación, transmitida en tiempo real (streamed) o no según el campo stream. Es la única ruta que genera consumo.CHAT
Primera llamada

Copia, pega y ejecuta.

El formato de solicitud es el de OpenAI: la mayoría de los SDK existentes funcionan cambiando la URL base y la clave.

curl
curl https://ia.venalabs.com/api/ai/v1/chat/completions \
  -H "Authorization: Bearer vena_sk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vena-eco",
    "messages": [{"role": "user", "content": "Résume ce texte en trois points."}],
    "max_tokens": 500
  }'
Respuesta

Dos contabilidades, servidas juntas.

El bloque usage incluye los tokens del MODELO (lo que cualquier cliente de OpenAI ya lee) y, con el prefijo vena_, lo que realmente se ha descontado de tu monedero. Los dos números difieren en un factor de 1 a 80 según la clase: confundirlos es lo que genera una factura sorpresa.

200 OK
{
  "id": "3f2a1c8e-…",
  "object": "chat.completion",
  "model": "vena-eco",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 412,
    "completion_tokens": 168,
    "total_tokens": 580,
    "vena_tokens_charged": 271,
    "vena_model_class": "ECO",
    "vena_multiplier": 1,
    "vena_balance_after": 7999729,
    "vena_usage_missing": false
  }
}

Los campos propios

  • vena_tokens_charged — Vena Tokens realmente debitados, multiplicador aplicado. Este es el número que importa.
  • vena_model_class — la clase aplicada (ECO, STANDARD, ADVANCED, FRONTIER).
  • vena_multiplier — el multiplicador vigente en el momento de calcular la cotización.
  • vena_balance_after — tu saldo disponible después de este débito, para que puedas mantener un contador sin necesidad de realizar una segunda llamada.
  • vena_usage_missing — true si nuestra pasarela no pudo confirmar el consumo y el débito recurre a una estimación. Esos movimientos están identificados y son reembolsables.

Campos de solicitud tenidos en cuenta

model, messages, max_tokens y stream. Cualquier otro campo se ignora en silencio: preferimos ignorarlo a declararlo sin cumplirlo; ajustar una temperatura que no cambiara nada sería peor que su ausencia.

Streaming

Líneas data:, luego [DONE].

Con stream en true, la respuesta llega mediante Server-Sent Events, con el protocolo esperado por los SDK de OpenAI: fragmentos data: sin nombre de evento, un fragmento final con finish_reason y el bloque usage completo, y por último la centinela data: [DONE].

text/event-stream
data: {"id":"3f2a…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"}}]}

data: {"id":"3f2a…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Trois "}}]}

data: {"id":"3f2a…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"vena_tokens_charged":271,"vena_balance_after":7999729}}

data: [DONE]

Se envía un comentario de mantenimiento de conexión (: hb) cada 200 ms. Los clientes SSE lo ignoran; es imprescindible detrás de un proxy, que corta las conexiones inactivas tras 30 a 60 segundos.

Si cortas la conexión a mitad de la generación, se te cobrará por lo que el modelo haya producido realmente, no por lo que hayas recibido ni por la reserva. Las otras dos bases de cálculo son erróneas, una en cada sentido.

Cuánto cuesta

Estima tu factura antes de la primera llamada.

Una llamada no cuesta una cantidad de tokens: cuesta una cantidad de Vena Tokens, que depende de la clase del modelo. Aquí tienes todo lo necesario para calcularlo tú mismo.

La fórmula completa

costo = techo( (tokens_entrada × 0,25 + tokens_salida × 1,0) × multiplicador )

El redondeo al alza se aplica una sola vez, al final de la fórmula. La salida pesa cuatro veces más que la entrada, lo que refleja la proporción de precios del proveedor. Los tokens de razonamiento cuentan como salida; los servidos desde la caché cuentan como entrada.

Los multiplicadores por clase

ECO
×1
STANDARD
×5
ADVANCED
×25
FRONTIER
×80

Modificables por la administración. Un cambio se aplica a la siguiente estimación, nunca de forma retroactiva: cada movimiento en tu historial congela los pesos y el multiplicador aplicados en ese momento. La ruta /models sirve siempre los valores en vigor.

Un ejemplo concreto

Una llamada con 2000 tokens de entrada y 800 tokens de salida cuesta 1300 Vena Tokens en clase Eco, 6500 en Standard, 32500 en Advanced y 104000 en Frontier. Sobre la cuota mensual de Pro (8 M), esto representa unas 6150 llamadas en Eco o 77 en Frontier.

Órdenes de magnitud redondeados, ofrecidos a título indicativo: tu consumo real depende de la longitud de tus intercambios. Solo el campo vena_tokens_charged de cada respuesta es vinculante.

En qué orden se consumen tus tokens

Tu saldo se compone de tres fondos: los tokens ganados al completar módulos, la cuota mensual de tu suscripción y las recargas compradas. El consumo se realiza por fecha de expiración creciente: el fondo que expira antes se consume primero.

Este orden es el único que nunca te resulta perjudicial: jamás dejamos expirar tokens que podrían haberse consumido.

Las recargas compradas son válidas durante 365 días y los tokens ganados al completar módulos, durante 90 días. La cuota mensual de la suscripción expira al final del periodo, sin acumulación.

Límites máximos por solicitud

Una llamada de suscriptor está limitada a 8,000 tokens de salida. Este límite acota el costo de la peor llamada: te protege de una generación que entre en bucle y a nosotros, de una factura del proveedor impredecible. Un max_tokens superior es aceptado y luego reducido a este límite.

Límites y salvaguardas

Lo que detiene una clave filtrada.

Tu saldo limita el gasto total, nunca la velocidad de transmisión. Una clave publicada por error en un repositorio Git respetaría perfectamente tu cuota mientras la agota en una sola noche. Tres salvaguardas se encargan de evitarlo.

Cadencia por clave — 60 llamadas/minuto

Más allá de esto, 429 RATE_LIMITED con un encabezado Retry-After. La clave permanece activa: reducir la velocidad no es condenar. Un cliente correcto detiene los envíos al primer rechazo.

Cadencia por cuenta — 30 llamadas/minuto

Se aplica a todo lo que consume la cuenta, incluido el chat. Tener cinco claves no multiplica por tanto el límite permitido: este es el límite tope que rige.

Interruptor automático — la clave se desactiva sola

En una ventana de 10 minutos, se monitorean tres señales y una sola basta: el volumen de llamadas, la insistencia tras los rechazos y, sobre todo, el gasto. Más allá de esto, la clave pasa a SUSPENDED, las llamadas posteriores reciben un 401 y recibes un correo electrónico indicando la clave afectada y el motivo.

Una clave desactivada nunca se vuelve a activar. Si tu secreto ha quedado expuesto, volver a activarla reabriría la puerta: la respuesta correcta es una rotación, que genera un nuevo secreto y anula el anterior.

Códigos de error

Lo que recibes, y por qué.

Los errores se devuelven en el formato de VenaLabs, no en el de OpenAI: {code, message, details}. Es deliberado — un rechazo por saldo insuficiente debe distinguirse de forma no ambigua de cualquier otro incidente, y el formato de OpenAI no contempla este concepto.

Códigos de error
EstadoCódigoFamiliaCuándoQué hacer
400VALIDATION_ERRORSolicitudCuerpo de la solicitud no válido. details contiene un mensaje por campo.Corrige el campo indicado.
400MALFORMED_REQUESTSolicitudEl cuerpo JSON es ilegible o un tipo recibido no coincide con el contrato.Valida el JSON y envía Content-Type: application/json.
400MODEL_UNKNOWNPlan y modeloEl modelo no existe o ha sido retirado del catálogo.Vuelve a consultar /models: es la única lista vinculante.
401API_KEY_INVALIDClave y alcanceClave desconocida, revocada, desactivada o fuera de alcance. Los cuatro casos devuelven exactamente la misma respuesta.Verifica el encabezado Authorization y el alcance requerido (MODELS o CHAT) en tu configuración; realiza una rotación solo si la clave se ha perdido, revocado o expuesto.
402INSUFFICIENT_TOKENSSaldo y cuotaEl saldo no cubre la estimación de esta llamada. No se realiza ninguna llamada ni se cobra nada.Compra una recarga o espera a la renovación de tu cuota.
402QUOTA_EXCEEDEDSaldo y cuotaSe ha alcanzado un límite del plan.Consulta details para obtener información sobre el límite afectado y la fecha de reinicio.
403PREMIUM_REQUIREDPlan y modeloEl plan de la cuenta ya no da acceso a la API para desarrolladores.Reanuda una suscripción Pro o Expert. Las claves existentes volverán a estar activas de inmediato.
403MODEL_NOT_ALLOWEDPlan y modeloLa clase solicitada no está disponible para el plan de la cuenta.Cambia de clase o cambia de plan.
405METHOD_NOT_ALLOWEDSolicitudEl método HTTP no coincide con la ruta solicitada.Utiliza GET para /models y POST para /chat/completions.
406NOT_ACCEPTABLESolicitudLa cabecera Accept solicita un formato que esta ruta no produce.Acepta application/json, o text/event-stream para una completación en streaming.
409WALLET_CONTENTIONDisponibilidadUna escritura concurrente impidió la reserva del wallet. No se registró ninguna retención ni débito.Vuelve a intentarlo tras un breve intervalo aleatorio.
413CONTEXT_TOO_LARGESolicitudLa conversación supera la ventana de contexto del modelo.Acorta el historial o elige un modelo con mayor ventana de contexto.
415UNSUPPORTED_MEDIA_TYPESolicitudEl Content-Type del cuerpo no es compatible.Envía el cuerpo con Content-Type: application/json.
429RATE_LIMITEDDisponibilidadCadencia superada o interruptor automático activado. details.keyDisabled es true en el segundo caso.Respeta Retry-After. Si la clave se desactivó, realiza una rotación.
500INTERNALDisponibilidadSe ha producido un incidente interno inesperado; details.reference identifica este incidente sin incluir tu contenido.Conserva details.reference y, a continuación, vuelve a intentarlo o contacta con soporte únicamente con dicha referencia — nunca con la clave ni el prompt.
503AI_UNAVAILABLEDisponibilidadLa pasarela de inferencia no está disponible momentáneamente.Vuelve a intentarlo. No se ha debitado nada: las llamadas no realizadas se reembolsan íntegramente.
Lo que esta API no hace

Los límites, claros desde el principio.

  • Solo una opción por llamada: el campo n no es compatible.
  • Sin herramientas, ni llamadas a funciones, ni salidas estructuradas: el campo tools se ignora.
  • Sin imágenes ni archivos de entrada: messages solo admite texto.
  • Sin temperatura ni top_p: estos ajustes no se exponen mientras no se apliquen.
  • Los identificadores vena-eco, vena-standard, vena-advanced y vena-frontier son alias estables de VenaLabs cuyo modelo subyacente puede evolucionar. Los demás identificadores indican el proveedor y el modelo real, por ejemplo anthropic/claude-sonnet-5.