Tovanix
Tovanix

Usar la pasarela de API de IA

Con una sola clave API llamas a modelos de varios proveedores y pagas según el uso real desde el saldo de la cuenta:

  • Crea la clave en «Servicios de IA → Pasarela de API → Claves API», elige un grupo de precios por proveedor y, si quieres, fija un tope de gasto mensual, que luego puedes cambiar en la lista de claves
  • Admite tres formatos de solicitud, OpenAI, Anthropic y Gemini; para integrarte normalmente solo cambias la dirección de la pasarela y la clave
  • Precio = precio oficial × factor del grupo de precios; algunos grupos tienen precio para horario fuera de pico
  • Antes de cada llamada se reserva un monto, al terminar se liquida según el uso real y los cargos se descuentan juntos del saldo una vez por minuto
  • «Uso y registros» ofrece estadísticas y el detalle de cada llamada

Para qué sirve la puerta de enlace

La pasarela de API de los Servicios de IA es un punto de entrada único para llamar a modelos de lenguaje grandes: con una sola clave API llamas a modelos de varios proveedores y pagas según el uso real desde el saldo de tu cuenta, sin abrir una cuenta ni recargar por separado con cada proveedor.

  • Los SDK oficiales funcionan tal cual: integrar suele significar cambiar base_url y api_key y nada más, con las estructuras de solicitud y respuesta sin cambios.
  • Admite tres formatos de solicitud, OpenAI, Anthropic y Gemini, y permite llamadas entre formatos: por ejemplo, llamar a un modelo Claude con el SDK de OpenAI; la pasarela hace la conversión automáticamente.
  • Los precios se fijan por grupo de precios: dentro de un grupo, cada modelo tiene un solo precio. Si el grupo tiene varias rutas y una falla, la solicitud pasa automáticamente a la siguiente ruta del mismo grupo, sin cambio de precio.

Crear una clave API

  • Abre la página de claves API: En la consola, ve a «Servicios de IA → Pasarela de API → Claves API» y pulsa «Crear clave» en la esquina superior derecha.
  • Define el nombre, los grupos de precios y el tope mensual: Conviene nombrarla según su uso, por ejemplo production, test o cursor. Para cada proveedor que tenga varios grupos disponibles, elige un «Grupo de precios»; si no eliges, se usa el grupo predeterminado de ese proveedor. Dejar vacío el tope de gasto mensual significa sin límite, y poner 0 significa que este mes no se permite gastar; después puedes cambiarlo desde la lista de claves con «Cambiar límite», lo que requiere verificar tu identidad.
  • Verifica tu identidad: Después de pulsar «Crear» tienes que verificar tu identidad: si tienes activada la verificación en dos pasos (2FA), escribe el código de 6 dígitos de tu app de autenticación; si no, escribe el código enviado a tu correo. Una vez verificado, durante los 10 minutos siguientes de esa sesión puedes crear más claves o cambiar topes sin volver a verificar.
  • Guarda la clave en texto plano de inmediato: La clave tiene la forma sk-nc- seguida de una cadena y se muestra una sola vez, porque el backend solo guarda su hash. Cópiala en tu gestor de contraseñas antes de cerrar el diálogo.

Cuando ese diálogo se cierra, el texto plano se pierde para siempre: la plataforma guarda un hash, no la clave. Si no la guardaste, la única opción es eliminar la clave y crear otra. La eliminación surte efecto de inmediato y todo lo que siga usando esa clave se desconectará.

Grupos de precios

El grupo de precios decide a qué precio se cobra cuando esta clave llama a los modelos de un proveedor: precio = precio oficial × factor del grupo. Los grupos se organizan por proveedor, y cada proveedor tiene sus propios grupos y un grupo predeterminado.

  • Al crear la clave solo hay que elegir para los proveedores que tienen dos o más grupos; los que tienen uno solo no requieren elección. El proveedor para el que no elijas usa su grupo predeterminado.
  • La columna «Grupo» de la lista de claves muestra el grupo y el factor elegidos para cada proveedor; pulsa «Cambiar» para modificarlo, y desde la siguiente llamada se cobra con el nuevo grupo.
  • Las llamadas solo usan las rutas del grupo elegido y nunca pasan a otro grupo, así que el precio de un mismo modelo no cambia porque cambie la ruta.

Si se desactiva el grupo elegido para un proveedor, la lista muestra «Grupo desactivado» y las llamadas con esta clave a los modelos de ese proveedor se rechazan (HTTP 403). Basta con pulsar «Cambiar» y elegir otro grupo.

Hacer tu primera llamada

La dirección de la pasarela es el mismo dominio de la consola. La página «Panel» tiene ejemplos de curl en los tres formatos, OpenAI, Anthropic y Gemini, y la ventana que aparece al crear una clave incluye otro; en todos, la dirección de la pasarela ya viene completada.

  • OpenAI — /v1/chat/completions — Encabezado Authorization, con el valor Bearer seguido de tu clave
  • Anthropic — /v1/messages — Encabezado x-api-key
  • Gemini — /v1beta/models/nombre-del-modelo:generateContent; en streaming, :streamGenerateContent — Encabezado x-goog-api-key, o el parámetro de URL ?key=
  • Con un SDK oficial, apunta base_url a la puerta de enlace y establece api_key con esta clave; el resto de tu código queda como está.
  • También están /v1/models (lista los modelos disponibles), /v1/embeddings (vectores de texto) y /v1/images/generations (generación de imágenes, cobrada por imagen), todos llamados con el formato de OpenAI.
  • En el campo model de la solicitud pon el identificador del modelo que aparece en su tarjeta del «Mercado de modelos». Si está mal escrito o el modelo no está publicado, se devuelve 404.

El mercado de modelos y cómo se muestran los precios

El mercado de modelos muestra todos los modelos disponibles por proveedor y permite buscar por nombre, slug, descripción o capacidad, mostrando junto a cada uno el contexto, la salida máxima y otros parámetros.

  • Precio = precio oficial × factor del grupo de precios. La pestaña «Todos» muestra los precios con el grupo predeterminado de cada proveedor; al abrir un proveedor puedes cambiar entre sus grupos. El multiplicador de la esquina superior derecha de cada tarjeta es el factor del grupo actual.
  • Los modelos que se cobran por token tienen dos precios, entrada y salida, por cada millón de tokens; si hay precio de lectura de caché, aparece en una línea aparte. Los modelos de imagen, audio, video y similares que se cobran por imagen, segundo, minuto o llamada muestran el precio unitario directamente en la tarjeta.
  • Algunas tarjetas tienen una línea «Prompts de más de» cierta longitud con su propio precio: si el prompt de una solicitud supera esa longitud, toda la solicitud se cobra al precio de esa línea.
  • En los modelos cuya tarjeta tiene una línea «Búsqueda web», usar la búsqueda web integrada del modelo se cobra aparte por número de búsquedas.

Si el grupo tiene precio para horario fuera de pico, la tarjeta muestra «Fuera de pico» y el factor, y al pasar el mouse por encima ves el horario pico; fuera del horario pico se aplica el precio del grupo multiplicado por ese factor, según la hora en que se envía la solicitud. Si la tarjeta dice «Aún no hay rutas en este grupo», lista los grupos en los que se puede usar ese modelo; si dice «No disponible», por ahora no se puede llamar desde ningún grupo.

Uso y registros

En «Servicios de IA → Pasarela de API → Uso y registros», la parte de arriba son estadísticas, que se pueden ver por 24 horas, 7 días, 30 días o 90 días (7 días por defecto); la parte de abajo es el detalle de llamadas.

  • Estadísticas: número de solicitudes, monto facturado, total de tokens (incluida la parte de caché), tasa de éxito y latencia promedio, además de la tendencia diaria y rankings por modelo y por clave.
  • Detalle: por cada llamada, la hora, el modelo, si fue en streaming, los tokens de entrada / salida / caché, el monto facturado, el factor, la latencia y el estado; se puede filtrar por slug de modelo.
  • El detalle solo registra las llamadas que llegaron al modelo, con estado «Éxito» o «Error»; los registros con «Error» no se cobran. Las solicitudes rechazadas antes de llegar al modelo (por ejemplo, por clave inválida, tope mensual alcanzado, saldo insuficiente o grupo desactivado) no aparecen en el detalle; el motivo está en el mensaje de error que devuelve la API.
  • La columna «Ratio» muestra el factor del grupo, sin el descuento de horario fuera de pico; lo que se cobra realmente en cada llamada es lo que indica la columna «Facturado USD».

Cómo se te cobra

Se cobra según el uso real desde el saldo de tu cuenta; no hace falta recargar este servicio por separado. El costo de cada llamada = precio oficial × factor del grupo; si el grupo tiene horario fuera de pico, en ese horario se multiplica además por el factor fuera de pico, según la hora en que se envía la solicitud.

  • Antes de cada llamada se reserva un monto calculado con la longitud de entrada de esa solicitud y la salida máxima del modelo; al terminar se liquida según el uso real y se libera lo que sobra. Si el saldo disponible no alcanza para esa reserva, se devuelve saldo insuficiente (HTTP 402), y el mensaje de error indica cuánto había que reservar y cuánto hay disponible.
  • Los cargos se acumulan llamada por llamada y se descuentan juntos del saldo una vez por minuto; en las facturas de «Finanzas» se genera cada hora una línea «Uso de Servicios de IA (resumen de 1 h)».
  • Cuando el saldo disponible baja a $5 o menos, la plataforma te avisa una vez por mensajes del sitio y otros canales de notificación; si vuelve a superar $5 y baja otra vez, te avisa de nuevo. Mientras tanto, las respuestas de la API incluyen los encabezados X-Tovanix-Balance-Low: 1 y X-Tovanix-Balance-Available (el monto disponible actual), para que tu programa pueda avisar de antemano que hay que recargar.
  • Cada clave puede tener su propio tope de gasto mensual, contado por mes calendario y restablecido automáticamente el mes siguiente. Se revisa antes de cada llamada: si lo gastado este mes más las llamadas en curso alcanza el tope, no se permiten más; como la última llamada se liquida según el uso real, el gasto del mes puede superar ligeramente el tope.

Precauciones

  • La clave en texto plano aparece solo al crearla: guárdala en ese momento.
  • Eliminar una clave surte efecto de inmediato y no se puede deshacer. Si solo quieres pausarla, pulsa «Desactivar» en la lista; después puedes pulsar «Activar».
  • Un tope mensual de 0 bloquea esa clave por completo durante el mes; no uses 0 para indicar ilimitado.
  • La pasarela procesa las solicitudes en el nivel estándar: el nivel de velocidad indicado en la solicitud (por ejemplo, speed: fast de Claude o service_tier de OpenAI) se ignora, y el cobro también es al precio estándar.
  • Al llamar con el formato de Anthropic e incluir la herramienta de búsqueda web, si la solicitud no indica un máximo de búsquedas, cada solicitud hace como máximo 10.

Solución de problemas

  • Devuelve 401 e indica que la clave no es válida o está desactivada — La clave está mal escrita, se eliminó o está desactivada — En la página «Claves API», confirma que la clave esté «Activada»; si está desactivada, basta con pulsar «Activar». Una clave eliminada no se puede recuperar: solo queda crear una nueva.
  • Devuelve 402 e indica que se alcanzó el tope de gasto mensual — El gasto de esta clave en el mes ya llegó al tope (un tope de 0 significa que este mes no se permite gastar) — Se restablece automáticamente el mes siguiente. Si no puedes esperar, en la página «Claves API» pulsa «Cambiar límite» en esa clave y sube el tope o déjalo vacío para quitar el límite (requiere verificar tu identidad); el nuevo tope se aplica desde la siguiente llamada.
  • Devuelve 402 e indica saldo insuficiente — El saldo disponible no alcanza para la reserva de esta solicitud — El mensaje de error indica cuánto había que reservar y cuánto hay disponible; recarga y vuelve a intentarlo.
  • Devuelve 403 o 503 e indica que el grupo está desactivado o que no hay rutas disponibles — El grupo que la clave tiene elegido para ese proveedor se desactivó, o por ahora ese modelo no tiene rutas disponibles en el grupo — En la página «Claves API», pulsa «Cambiar» y elige otro grupo; la tarjeta del modelo en el «Mercado de modelos» lista los grupos en los que se puede usar. También puedes volver a intentarlo más tarde.
  • La factura no coincide con el precio del mercado — La pestaña «Todos» muestra el precio del grupo predeterminado, pero la clave tiene otro grupo; o la llamada cayó en horario fuera de pico, el prompt superó el umbral de contexto largo o se usó la búsqueda web — Lo que cuenta es el monto facturado de cada registro en «Uso y registros».
  • Una aplicación en producción se desconecta de repente — La clave se eliminó o se desactivó — Si está desactivada, pulsa «Activar» en la lista para recuperarla; si se eliminó, solo queda crear una nueva y reemplazar la clave anterior en la aplicación.

Preguntas frecuentes

¿Cuánto código hay que cambiar para integrarse?

Normalmente solo dos cosas: apuntar base_url a la pasarela y cambiar api_key por una clave de la plataforma. La pasarela es compatible con los SDK y protocolos oficiales: el cuerpo de la solicitud, la estructura de la respuesta y el formato de streaming se mantienen iguales.

¿Por qué mi factura no coincide con el precio del mercado de modelos?

La pestaña «Todos» muestra el precio del grupo predeterminado de cada proveedor; si tu clave tiene otro grupo, se cobra con el precio de ese grupo. Además, el descuento del horario fuera de pico, el cambio de precio de toda la solicitud cuando el prompt supera el umbral de contexto largo y el cobro aparte por cada búsqueda web hacen que el costo de una llamada difiera del precio mostrado. Lo que cuenta es el monto facturado de cada registro en «Uso y registros».

¿Cómo controlo el gasto de un proyecto?

Crea una clave solo para ese proyecto y fija un tope de gasto mensual. El tope es por clave, así que los proyectos no se afectan entre sí; para ajustarlo después, pulsa «Cambiar límite» en la lista de claves (requiere verificar tu identidad).

Páginas relacionadas: Centro de ayuda · Guías y preguntas frecuentes · Servicios de IA · Documentación de la API

Cargando…