Cree un libro mayor de facturación de API de IA: cotice, reserve, liquide y concilie cada llamada modelo

La facturación de API de IA orientada al cliente no puede ser una exportación mensual del uso sin procesar del proveedor. Si una puerta de enlace expone varios modelos a inquilinos, equipos o socios, la facturación debe responder a una pregunta más difícil antes de que exista la factura: ¿debería permitirse esta solicitud ahora mismo y cómo se explicará su costo más adelante?

El patrón práctico es un libro de facturación con cuatro etapas: cotización, reserva, liquidación y conciliación. Cotiza el costo probable antes de la solicitud. Reserve suficiente presupuesto del inquilino para cubrir el peor de los casos permitido. Liquidar el costo real después de conocer el uso. Concilie el libro mayor de la puerta de enlace con los registros del lado del proveedor para que las facturas sigan siendo defendibles.

Este artículo describe el bucle de control para una puerta de enlace API multimodelo. Es útil ya sea que la puerta de enlace facture a equipos internos, clientes de prepago, clientes de agencias o socios intermedios.

El problema de facturación: el uso del proveedor no es una factura del cliente

Hecho: los principales proveedores de IA no exponen un contador de token universal ni un precio universal. OpenAI publica precios por modelo con tasas de token de entrada, entrada en caché y salida separadas. El almacenamiento en caché de avisos de OpenAI informa el uso de tokens almacenados en caché en el campo de uso de respuesta de API. Los documentos antrópicos separan los contadores para los tokens de entrada normales, los tokens de entrada de creación de caché, los tokens de entrada de lectura de caché y los tokens de salida. Los precios de Gemini distinguen entradas, salidas y otras categorías de tokens, incluido el uso de modalidades específicas, como tokens de audio.

Eso significa que una puerta de enlace no puede facturar de forma segura multiplicando total_tokens por un precio. Necesita adaptadores específicos del proveedor detrás de un esquema de facturación neutral para el proveedor.

El problema se vuelve más visible en estas situaciones:

• Créditos prepagos: la puerta de enlace debe rechazar las solicitudes antes de que el inquilino gaste menos de cero.
• Recargos del socio: el socio necesita su propia factura de cara al cliente, no una copia de la factura del proveedor.
• Transmisión: la respuesta comienza antes de que se conozca el uso final del token.
• Almacenamiento en caché rápido: la entrada almacenada en caché puede ser más económica que la entrada sin caché, pero solo si se mide por separado.
• Razonamiento y uso de herramientas: algunos modelos exponen dimensiones de uso adicionales, clases de resultados ocultas o unidades de medios.
• Cambios de precios del proveedor: una factura del mes pasado aún debe ser reproducible después de que cambie la hoja de tarifas.

Recomendación: trate la facturación como un libro de contabilidad financiero de solo anexos, no como una consulta en el panel de control sobre los registros de solicitudes.

La arquitectura central

Una arquitectura de facturación confiable tiene seis componentes:

1. Cuenta de inquilino: cliente, espacio de trabajo, cliente revendedor o centro de costos interno.
2. Servicio de hoja de tarifas: precios versionados para proveedor, modelo, clase de facturación, moneda y regla de margen.
3. Estimador: calcula una cotización de verificación previa a partir de los parámetros de solicitud y la política del modelo.
4. Libro mayor de reservas: mantiene el presupuesto antes de que comience la llamada al proveedor.
5. Normalizador de uso: convierte campos de uso específicos del proveedor en unidades de facturación interna.
6. Trabajos de liquidación y conciliación: finalice los cargos y compárelos con los registros del proveedor.

El flujo de control tiene este aspecto:

solicitud de cliente
  -> autenticar inquilino y clave
  -> seleccionar modelo y versión de hoja de tarifas
  -> estimar el costo de entrada y salida máxima
  -> reservar saldo del inquilino
  -> proveedor de llamadas
  -> normalizar el uso devuelto
  -> liquidar el costo real
  -> liberar reserva no utilizada
  -> emitir evento de libro mayor listo para factura

La elección de diseño importante es que la solicitud no se cumpla simplemente. Se controla financieramente antes y después de la ejecución.

Paso 1: cotización antes de la llamada del proveedor

Una cotización de verificación previa debe ser lo suficientemente pesimista como para hacer cumplir los presupuestos, pero lo suficientemente explicable como para mostrársela a los clientes o socios.

Las entradas generalmente incluyen:

• ID de inquilino y plan de facturación;
• ID de clave API o ID de proyecto;
• ID del proveedor y del modelo después de aplicar las reglas de enrutamiento;
• tokens de entrada estimados sin caché;
• elegibilidad conocida de entrada en caché, si está disponible;
• max_tokens, max_output_tokens o límite de salida equivalente;
• herramienta, imagen, audio u otros parámetros de modalidad;
• regla de precios de revendedor, descuento o margen de beneficio para socios;
• política de moneda y redondeo.

Una fórmula de cotización simple para la generación de texto podría ser:

coste_estimado =
  tokens_de_entrada_uncached_estimados * tasa_de_entrada
+ tokens_de_entrada_caché_estimados * tasa_de_entrada_caché
+ max_output_tokens * tasa_de salida+ solicitud_tarifa
+ socio_markup

Recomendación: cuando se desconoce la longitud de salida final, reserve contra la salida máxima configurada. Si la aplicación deja el límite de salida ilimitado, la puerta de enlace debe aplicar un inquilino o modelo predeterminado. La ejecución del presupuesto no puede ser determinista si no existe una responsabilidad máxima.

Esto puede rechazar algunas solicitudes que habrían sido económicas en la práctica. Ésa es la compensación. Para los sistemas prepago, el valor predeterminado más seguro es la reserva pesimista con los fondos no utilizados liberados después de la liquidación. Para los clientes empresariales facturados, los equipos pueden permitir excedentes leves y utilizar la cotización principalmente para alertas.

Paso 2: reservar el presupuesto del inquilino

La reserva protege la cuenta del inquilino para que no gaste más del saldo permitido. Debe ser atómico: o la reserva se realiza correctamente y puede comenzar la llamada del proveedor, o la solicitud se rechaza antes de que se incurra en ningún costo del proveedor.

Un registro de reserva puede incluir:

{
  "reservation_id": "res_01J...",
  "tenant_id": "tenant_123",
  "api_key_id": "key_456",
  "request_id": "req_789",
  "proveedor": "ejemplo_proveedor",
  "modelo": "modelo-a",
  "rate_card_version": "2026-08-01",
  "quoted_amount": "0.032100",
  "moneda": "USD",
  "estado": "reservado",
  "expires_at": "2026-08-11T12:05:00Z"
}

Utilice vencimientos de reserva cortos para fallas de red y desconexiones de clientes. Un trabajo de limpieza debería liberar las reservas vencidas que nunca llegaron a liquidarse. Sin embargo, no libere una reserva simplemente porque el cliente se desconectó; la llamada al proveedor aún podría completarse e incurrir en costos. Realice un seguimiento del estado de la solicitud del proveedor por separado.

Recomendación: haga que la reserva sea idempotente mediante el ID de solicitud o la clave de idempotencia. Los reintentos de clientes, puertas de enlace o trabajadores no deben crear múltiples retenciones de presupuesto para la misma solicitud lógica.

Paso 3: normalizar el uso del proveedor

Las respuestas de los proveedores deben convertirse en un pequeño esquema interno. Manténgalo estable incluso cuando los proveedores agreguen nuevos campos de uso.

Un esquema práctico de uso normalizado:

{
  "input_uncached_tokens": 1200,
  "input_cached_tokens": 800,
  "cache_write_tokens": 0,
  "tokens_salida": 650,
  "tokens_de_salida_ocultos_de_razonamiento": 0,
  "tool_or_media_units": [],
  "request_fee_units": 1,
  "provider_request_id": "prov_abc",
  "usage_source": "provider_response",
  "is_estimated": falso
}

Este esquema no es intencionalmente idéntico a la respuesta de ningún proveedor. Capta las dimensiones de facturación que necesitan las facturas y al mismo tiempo conserva vías de escape para unidades específicas del proveedor.

Los tokens almacenados en caché necesitan su propia línea

Hecho: el precio del almacenamiento en caché de avisos puede ser diferente al de la entrada sin caché. Si los tokens almacenados en caché se combinan con el total de tokens de entrada, es posible que se le cobre de más al cliente o que la puerta de enlace subestime el costo del proveedor. La entrada almacenada en caché debería aparecer como su propia clase de facturación tanto en el libro mayor como en la factura.

Las escrituras y lecturas de caché no siempre son las mismas

Algunos proveedores distinguen entre crear entradas de caché y leer desde la caché. El normalizador no debe asumir que la entrada almacenada en caché siempre significa una tarifa de facturación. Si un proveedor tiene tokens de escritura de caché y tokens de lectura de caché, asignelos por separado o consérvelos como subunidades específicas del proveedor.

El razonamiento y los resultados ocultos necesitan una política

Algunos modelos exponen el uso relacionado con el razonamiento o contadores de salida ocultos. Si el proveedor factura esas unidades, la puerta de enlace debe decidir si las muestra directamente, las incluye en una categoría de salida o las enumera como una línea de factura separada.

Recomendación: las facturas dirigidas al cliente deben utilizar un lenguaje sencillo. Por ejemplo: "tokens de salida de razonamiento" es más claro que el nombre de un campo de proveedor sin formato. Mantenga los campos sin procesar disponibles para la auditoría, pero no obligue a todos los clientes a comprender los aspectos internos del proveedor.

Paso 4: liquidar el coste real

La liquidación convierte el uso normalizado en asientos finales del libro mayor. Debe ser solo para anexar y hacer referencia a la versión de la hoja de tarifas utilizada para la solicitud.

Un evento resuelto podría verse así:

{
  "ledger_event_id": "led_01J...",
  "event_type": "liquidación",
  "tenant_id": "tenant_123",
  "request_id": "req_789",
  "reservation_id": "res_01J...",
  "proveedor": "ejemplo_proveedor",
  "modelo": "modelo-a",
  "rate_card_version": "2026-08-01",
  "líneas": [
    {
      "billing_class": "input_uncached_tokens",
      "cantidad": 1200,
      "unidad": "token",
      "precio_unitario": "0.00000250",
      "cantidad": "0,003000"
    },
    {
      "billing_class": "input_cached_tokens",
      "cantidad": 800,
      "unidad": "token",
      "precio_unitario": "0.00000125",
      "cantidad": "0,001000"
    },
    {
      "billing_class": "output_tokens",
      "cantidad": 650,
      "unidad": "token","precio_unitario": "0.00001000",
      "cantidad": "0,006500"
    }
  ],
  "monto_total": "0.010500",
  "moneda": "USD",
  "estado": "resuelto"
}

Si la solicitud se reservó para 0,032100 y se liquidó en 0,010500, el libro mayor libera 0,021600 al saldo disponible.

Recomendación: nunca vuelva a calcular las líneas de facturas antiguas a partir de la tabla de precios actual. Almacene versiones inmutables de la hoja de tarifas y adjunte el ID de la versión a cada evento de cotización, reserva y liquidación. De lo contrario, es posible que sea imposible reproducir una factura después de que un proveedor actualice los precios de los modelos.

Solicitudes de streaming: reservar primero, liquidar después

La transmisión por secuencias complica la facturación porque el usuario comienza a recibir resultados antes de que la puerta de enlace conozca el uso final. La respuesta no es saltarse las comprobaciones previas al vuelo. La puerta de enlace debe reservarse antes de abrir la transmisión.

Utilice este flujo de trabajo:

1. Estime los tokens de entrada y el costo máximo de producción.
2. Reservar presupuesto del inquilino.
3. Abra el flujo de proveedores.
4. Reenviar fragmentos al cliente.
5. Capture el uso final cuando el proveedor lo envíe o cuando esté disponible un registro de uso de seguimiento.
6. Liquidar el coste real y liberar la reserva no utilizada.

Si el uso final no está disponible, marque la liquidación como estimada en lugar de fingir que es exacta:

"usage_source": "gateway_estimate",
"is_estimated": verdadero,
"reconciliation_status": "pendiente"

Recomendación: la conciliación diaria debe priorizar los eventos de transmisión estimados, las solicitudes fallidas, los tiempos de espera y los reintentos. Estas son las áreas con mayor probabilidad de crear variaciones entre los registros de la puerta de enlace y las facturas de los proveedores.

Reglas de marcado y control de versiones de la hoja de tarifas

Una hoja de tarifas debe ser un objeto versionado, no una hoja de cálculo mutable.

Campos mínimos:

• proveedor;
• ID del modelo;
• clase de facturación;
• unidad, como token, solicitud, imagen, segundo de audio o unidad de herramienta;
• precio unitario;
• moneda;
• marcas de tiempo efectivas de inicio y finalización;
• política de redondeo;
• plan de inquilino o regla de margen de beneficio de socio;
• referencia de origen y metadatos de aprobación.

Las reglas de marcado deben ser explícitas. Por ejemplo:

• Costo más: costo del proveedor más 20 %.
• Venta minorista fija: el inquilino paga un precio simbólico fijo independientemente del precio del proveedor.
• Escalonados: primeros 10 millones de tokens a una tasa, luego a una tasa más baja.
• Créditos incluidos: el uso agota una asignación mensual antes de que comience la facturación excedente.

Compensación: el control de versiones de la hoja de tarifas agrega trabajo operativo, pero evita que las disputas sobre facturas se conviertan en arqueología. Un agente de atención al cliente debería poder explicar por qué una solicitud del 3 de agosto se facturó a una tarifa específica sin consultar el precio actual del proveedor.

Separar el libro de facturación del análisis

El análisis y la facturación tienen diferentes tolerancias. Los análisis se pueden agregar, retrasar, muestrear o corregir. La facturación debe ser completa, idempotente, auditable y explicable.

Utilice análisis para preguntas como:

• ¿Qué equipos utilizan más tokens?
• ¿Qué modelos están creciendo más rápidamente?
• ¿Dónde puede reducir el coste el almacenamiento en caché rápido?
• ¿Qué claves generan solicitudes inusualmente costosas?

Utilice el libro de facturación para preguntas como:

• ¿Se autorizó esta solicitud contra el saldo del inquilino?
• ¿Qué versión de la hoja de tarifas generó este cargo?
• ¿Se liberó la reserva no utilizada?
• ¿La factura del cliente coincide con el uso liquidado?
• ¿El uso de la puerta de enlace coincide con el uso del lado del proveedor?

Hecho: Las convenciones semánticas de OpenTelemetry GenAI incluyen atributos de uso de tokens, como tokens de entrada y salida. Esto es útil para la observabilidad y para unir trazas a eventos de costos. Pero los atributos de telemetría no sustituyen a las hojas de tarifas, las reservas, la liquidación, el redondeo y el estado de la factura.

Flujo de trabajo de conciliación diario

La conciliación compara el libro de contabilidad liquidado de la puerta de enlace con el uso del lado del proveedor. El objetivo no es un acuerdo perfecto en todos los campos intermedios. El objetivo es detectar variaciones materiales con suficiente antelación para corregir facturas, hojas de tarifas o adaptadores.

Un trabajo diario práctico:

1. Agrupe los eventos del libro mayor de la puerta de enlace por proveedor, modelo, inquilino o clave API, clase de facturación y día UTC.
2. Obtenga el uso del lado del proveedor agrupado por dimensiones disponibles, como ID de clave API, modelo y día.
3. Normalizar las exportaciones de proveedores a través del mismo código de adaptador utilizado para las respuestas a las solicitudes cuando sea posible.
4. Compare cantidades y costos por clase de facturación.
5. Marcar la variación por encima de los umbrales, como una diferencia de cantidad del 0,5 % o cualquier diferencia de costo absoluta grande.
6. Clasifique las causas de la variación: estimaciones de transmisión, reintentos, solicitudes fallidas, contabilidad de caché, cambios de alias de modelo, registros de proveedores retrasados o ID de solicitud faltantes.
7. Cree eventos de ajuste en lugar de editar eventos de liquidación antiguos.

Recomendación: use claves API de proveedor por inquilino cuando sea operativamente viable porque simplifica la conciliación. Si eso genera demasiada sobrecarga de administración de claves, asigne los ID de inquilinos internos a los metadatos del proveedor cuando sean compatibles y mantenga un puente de ID de solicitud confiable.

Líneas de factura que los clientes pueden entender

Una factura dirigida al cliente no debe reflejar el formato JSON del proveedor. Debe explicar la factura en términos comerciales estables.

Columnas de factura útiles:

• rango de fechas;
• etiqueta de clave de inquilino, proyecto o API;
• modelo o perfil de modelo;
• recuento de solicitudes;
• tokens de entrada sin caché;
• tokens de entrada almacenados en caché;
• tokens de salida;
• unidades de medios o herramientas, si corresponde;
• descuentos, créditos o márgenes;
• monto total y moneda.

Para los socios, incluya tanto el costo mayorista como el cargo minorista solo si el modelo de negocio lo requiere. Muchas facturas de revendedores deben mostrar solo el uso minorista, mientras que los paneles de control de socios pueden mostrar el margen por separado.

Compensación: un esquema de facturación unificado mejora la legibilidad, pero los detalles de facturación específicos del proveedor aún necesitan vías de escape. Mantenga las líneas de factura simples de forma predeterminada y proporcione una exportación para clientes avanzados que necesitan campos de auditoría detallados.

Lista de verificación de implementación

Antes del lanzamiento

• Defina clases de facturación normalizadas para todos los proveedores admitidos.
• Cree versiones de hojas de tarifas inmutables con fechas de vigencia.
• Requerir límites de salida o aplicar valores predeterminados de puerta de enlace.
• Implementar reservas atómicas con claves de idempotencia.
• Establece reglas de redondeo para cada moneda.
• Decida cómo facturar los tokens almacenados en caché, los tokens de razonamiento, las unidades de medios y las tarifas de solicitud.
• Reintentos de prueba, tiempos de espera, desconexiones de clientes y errores de proveedores.
• Cree un mecanismo de eventos de ajuste en lugar de editar eventos liquidados.

Durante el manejo de solicitudes

• Autenticar inquilino y clave.
• Resolver el modelo final después de la política de enrutamiento y reserva.
• Seleccione la versión correcta de la hoja de tarifas.
• Cotiza el coste en el peor de los casos.
• Reserve saldo o rechace la solicitud.
• Registre el ID de solicitud del proveedor cuando esté disponible.
• Normalizar el uso a partir de la respuesta.
• Liquidar, liberar reservas no utilizadas y emitir eventos listos para facturar.

Después del manejo de la solicitud

• Ejecute la conciliación diaria por proveedor, clave, modelo, clase de facturación y día.
• Revisar los acuerdos estimados de streaming.
• Marcar el uso del modelo si faltan entradas en la hoja de tarifas.
• Supervisar la variación causada por la contabilidad de tokens almacenados en caché.
• Genere vistas previas de las facturas de los clientes antes de la facturación final.

Predicciones para planificar

Predicción: la facturación de la API de IA será más multidimensional, no menos. Es probable que las clases de token, las clases de caché, las unidades de medios, la ejecución de herramientas y los contadores relacionados con el razonamiento sigan expandiéndose a medida que cambien las capacidades del modelo.

Predicción: los clientes esperarán explicaciones de uso a nivel de solicitud, clave, proyecto y factura. Un total mensual sin líneas de pedido rastreables será insuficiente para los equipos que revenden acceso a API o aplican presupuestos prepagos.

Predicción: las pasarelas que ya separan cotización, reserva, liquidación y conciliación se adaptarán más rápido a los nuevos modelos de precios porque pueden agregar clases de facturación sin tener que reescribir todo el sistema de facturación.

Conclusión procesable

Si expone varios proveedores de IA a través de una puerta de enlace, cree el libro de facturación antes de que las disputas de facturación fuercen el problema. Empieza con cuatro garantías:

1. Cada solicitud facturable recibe una cotización de verificación previa.
2. Cada inquilino prepago o con límite tiene un presupuesto reservado antes de que comience la llamada del proveedor.
3. Cada respuesta del proveedor se normaliza en clases de facturación estables.
4. Cada factura se puede conciliar con el uso del proveedor y la versión exacta de la hoja de tarifas utilizada en ese momento.

Ese bucle de control hace que la facturación unificada de API de IA sea comprensible para los clientes, ejecutable para créditos prepagos, flexible para márgenes de beneficio de socios y auditable cuando cambian los precios de los proveedores o los formatos de uso.

Lectura relacionada

• unir seguimientos de LLM con registros de uso y costos
• creación de portales de revendedor con medición de uso de inquilinos
• usar el almacenamiento en caché rápido y mantener la facturación comprensible