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.
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.
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.
Authorization: Bearer vena_sk_VOTRE_CLECuatro 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é.
Dos rutas, y eso es todo.
https://ia.venalabs.com/api/ai/v1| Método | Ruta | Propósito | Ámbito requerido |
|---|---|---|---|
| GET | /api/ai/v1/models | El 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/completions | Una completación, transmitida en tiempo real (streamed) o no según el campo stream. Es la única ruta que genera consumo. | CHAT |
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 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
}'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.
{
"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.
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].
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.
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.
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.
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.
| Estado | Código | Familia | Cuándo | Qué hacer |
|---|---|---|---|---|
| 400 | VALIDATION_ERROR | Solicitud | Cuerpo de la solicitud no válido. details contiene un mensaje por campo. | Corrige el campo indicado. |
| 400 | MALFORMED_REQUEST | Solicitud | El cuerpo JSON es ilegible o un tipo recibido no coincide con el contrato. | Valida el JSON y envía Content-Type: application/json. |
| 400 | MODEL_UNKNOWN | Plan y modelo | El modelo no existe o ha sido retirado del catálogo. | Vuelve a consultar /models: es la única lista vinculante. |
| 401 | API_KEY_INVALID | Clave y alcance | Clave 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. |
| 402 | INSUFFICIENT_TOKENS | Saldo y cuota | El 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. |
| 402 | QUOTA_EXCEEDED | Saldo y cuota | Se ha alcanzado un límite del plan. | Consulta details para obtener información sobre el límite afectado y la fecha de reinicio. |
| 403 | PREMIUM_REQUIRED | Plan y modelo | El 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. |
| 403 | MODEL_NOT_ALLOWED | Plan y modelo | La clase solicitada no está disponible para el plan de la cuenta. | Cambia de clase o cambia de plan. |
| 405 | METHOD_NOT_ALLOWED | Solicitud | El método HTTP no coincide con la ruta solicitada. | Utiliza GET para /models y POST para /chat/completions. |
| 406 | NOT_ACCEPTABLE | Solicitud | La cabecera Accept solicita un formato que esta ruta no produce. | Acepta application/json, o text/event-stream para una completación en streaming. |
| 409 | WALLET_CONTENTION | Disponibilidad | Una escritura concurrente impidió la reserva del wallet. No se registró ninguna retención ni débito. | Vuelve a intentarlo tras un breve intervalo aleatorio. |
| 413 | CONTEXT_TOO_LARGE | Solicitud | La conversación supera la ventana de contexto del modelo. | Acorta el historial o elige un modelo con mayor ventana de contexto. |
| 415 | UNSUPPORTED_MEDIA_TYPE | Solicitud | El Content-Type del cuerpo no es compatible. | Envía el cuerpo con Content-Type: application/json. |
| 429 | RATE_LIMITED | Disponibilidad | Cadencia 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. |
| 500 | INTERNAL | Disponibilidad | Se 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. |
| 503 | AI_UNAVAILABLE | Disponibilidad | La pasarela de inferencia no está disponible momentáneamente. | Vuelve a intentarlo. No se ha debitado nada: las llamadas no realizadas se reembolsan íntegramente. |
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.