Consumo y facturación

El consumo de cada solicitud llega en cada respuesta: factura a partir de él con confianza. El saldo actual se consulta con GET /v1/dashboard/balance.

Consumo por solicitud

Cada respuesta de /v1/messages incluye un objeto usage con el recuento de tokens:

{
"usage": {
"input_tokens": 48,
"output_tokens": 92,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}

En chat-completions , los mismos números aparecen como prompt_tokens, completion_tokens y total_tokens.

Saldo de la clave: GET /v1/dashboard/balance

Devuelve el saldo actual de la clave. Responde al instante y usa la misma clave que la API.

curl -H "Authorization: Bearer sk-YOUR_KEY_HERE" \
https://api.oneprovider.dev/v1/dashboard/balance

Respuesta 200 OK:

{
"object": "balance",
"balance_usd": 54.77,
"expires_at": "2026-07-29T19:00:00Z",
"is_active": true,
"last_synced_at": "2026-06-29T19:52:00Z"
}

• balance_usd: el saldo disponible de la clave en USD.
• expires_at: vencimiento de la clave (ISO 8601 UTC, null si no tiene).
• is_active: false si la clave está en pausa o desactivada.
• last_synced_at: cuándo se actualizó el saldo por última vez.

Endpoints de saldo compatibles con OpenAI

Apps como NextChat y LobeChat leen el saldo desde rutas al estilo OpenAI. Funcionan con la misma clave en Authorization: Bearer:

Errores: 401 si falta el encabezado Authorization: Bearer o no es válido; 429 si superas el límite de frecuencia (los endpoints de saldo se limitan por IP). El saldo y el gasto por solicitud también están en el panel (la página “Consumo” en el bot @oneprovider_robot y en app.oneprovider.dev ).

Tarifas efectivas

Facturamos una tarifa fija por cada 1M de tokens, la publicada en /pricing . No hay multiplicador, mínimo ni redondeo. La cuenta es:

cost = (input_tokens / 1_000_000) * rate_in
+ (output_tokens / 1_000_000) * rate_out
+ (cache_read_input_tokens / 1_000_000) * (rate_in * 0.10)
+ (cache_creation_input_tokens / 1_000_000) * (rate_in * 1.25)

• Las lecturas de caché se facturan al 10 % de la tarifa de entrada en la mayoría de los modelos.
• La creación de caché (la primera vez que se escribe un punto de caché) se factura al 125 % de la tarifa de entrada en la mayoría de los modelos.
• Los multiplicadores 0,10 y 1,25 de la fórmula son los habituales: las tarifas exactas de lectura y escritura de caché de cada modelo están en la tabla de modelos .

Cuando se acaba el saldo

Cuando el saldo de la clave llega a cero, las solicitudes con ella devuelven 429 con error.type insufficient_balance, error.code insufficient_quota y el encabezado x-should-retry: false:

HTTP/1.1 429 Too Many Requests
x-should-retry: false
Content-Type: application/json
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}

No reintentes: revisa el saldo del panel y el límite de la clave (la página “Claves”), recarga el panel si hace falta y vuelve a enviar la solicitud (cómo ). Todos los demás códigos están en Códigos de error .

Rate-limit (429)

Demasiadas solicitudes en poco tiempo devuelven 429 rate_limit_error. La respuesta puede traer un encabezado Retry-After en segundos:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded; retry later"
}
}

Si hay Retry-After, espera al menos ese tiempo; si no, reintenta con una pausa creciente. Si los 429 no cesan, reduce la concurrencia en el cliente. Las solicitudes limitadas por frecuencia no consumen saldo.

Precisión del consumo por solicitud

Los objetos usage de cada solicitud suman exactamente el gasto real por clave. Verificado el 2026-05-08 en una muestra de 24 h con 25 845 solicitudes: la diferencia máxima fue inferior a $0.001 (redondeo en el sexto decimal). Factura con confianza a partir del usage de cada solicitud.