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

La facturación AI API de cara 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. OpenAI el almacenamiento en caché indica el uso de tokens almacenados en caché en el campo de uso de respuesta API. Anthropic documenta contadores separados para tokens de entrada normales, tokens de entrada de creación de caché, tokens de entrada de lectura de caché y tokens de salida. Gemini los precios distinguen entradas, salidas y otras categorías de tokens, incluido el uso específico de la modalidad, 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 que solo se adjunta, no como una consulta del panel 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 internas.
6. Trabajos de liquidación y conciliación: finaliza los cargos y los compara con los registros del proveedor.

El flujo de control tiene este aspecto:

client request
  -> authenticate tenant and key
  -> select model and rate-card version
  -> estimate input and max output cost
  -> reserve tenant balance
  -> call provider
  -> normalize returned usage
  -> settle actual cost
  -> release unused reservation
  -> emit invoice-ready ledger event

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

Paso 1: cotiza antes de que llame el 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 normalmente incluyen:

• ID de inquilino y plan de facturación;
• API ID de clave o ID de proyecto;
• ID de proveedor y 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:

estimated_cost =
  estimated_uncached_input_tokens * input_rate
+ estimated_cached_input_tokens   * cached_input_rate
+ max_output_tokens               * output_rate
+ request_fee
+ partner_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 la llamada del proveedor puede comenzar, 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",
  "provider": "example_provider",
  "model": "model-a",
  "rate_card_version": "2026-08-01",
  "quoted_amount": "0.032100",
  "currency": "USD",
  "status": "reserved",
  "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 del proveedor 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,
  "output_tokens": 650,
  "reasoning_or_hidden_output_tokens": 0,
  "tool_or_media_units": [],
  "request_fee_units": 1,
  "provider_request_id": "prov_abc",
  "usage_source": "provider_response",
  "is_estimated": false
}

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 resultados 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 contables finales. Debe ser de solo anexo 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": "settlement",
  "tenant_id": "tenant_123",
  "request_id": "req_789",
  "reservation_id": "res_01J...",
  "provider": "example_provider",
  "model": "model-a",
  "rate_card_version": "2026-08-01",
  "lines": [
    {
      "billing_class": "input_uncached_tokens",
      "quantity": 1200,
      "unit": "token",
      "unit_price": "0.00000250",
      "amount": "0.003000"
    },
    {
      "billing_class": "input_cached_tokens",
      "quantity": 800,
      "unit": "token",
      "unit_price": "0.00000125",
      "amount": "0.001000"
    },
    {
      "billing_class": "output_tokens",
      "quantity": 650,
      "unit": "token",
      "unit_price": "0.00001000",
      "amount": "0.006500"
    }
  ],
  "total_amount": "0.010500",
  "currency": "USD",
  "status": "settled"
}

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 del modelo.

Solicitudes de transmisión: reserve primero, liquide después

La transmisión 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 la transmisión del proveedor.
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": true,
"reconciliation_status": "pending"

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 de 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;
• metadatos de aprobación y referencia de origen.

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.
• Escalonado: primeros 10 millones de tokens a una tarifa, luego a una tarifa 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

Los 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ápido?
• ¿Dónde puede reducir el coste el almacenamiento en caché de avisos?
• ¿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 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 eventos del libro mayor de puerta de enlace por proveedor, modelo, inquilino o clave API, clase de facturación y día UTC.
2. Obtener el uso del lado del proveedor agrupado por dimensiones disponibles, como API ID de clave, 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. Clasificar 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. Crear eventos de ajuste en lugar de editar eventos de liquidación antiguos.

Recomendación: use claves del proveedor API por inquilino cuando sea operativamente viable porque simplifica la conciliación. Si esto 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 proveedor JSON. Debe explicar la factura en términos comerciales estables.

Columnas de factura útiles:

• intervalo de fechas;
• inquilino, proyecto o API etiqueta clave;
• 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;
• importe total y moneda.

Para los socios, incluya el costo mayorista y 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 necesiten 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.
• Crear 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.
• Crear un mecanismo de eventos de ajuste en lugar de editar eventos resueltos.

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 de 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 mediante IA API 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 API acceso 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 práctica

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. Comience 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 IA unificada API facturación sea comprensible para los clientes, ejecutable para créditos prepagos, flexible para los márgenes de los socios y auditable cuando los precios del proveedor o los formatos de uso cambian.

Lectura relacionada

• unir seguimientos de LLM con el uso y el costo registros
• creación de portales de revendedor con medición de uso de inquilinos
• utilización del almacenamiento en caché de avisos y manteniendo la facturación comprensible