Skip to main content
GET
Utilice una API Key para consultar los gastos de un período, con filtros por modelo y agrupación por modelo, día natural o ambos. El resultado agregado se devuelve directamente, sin crear tareas ni consultar su estado periódicamente.

Autenticación

string
requerido
Utilice la misma API Key que para llamar a los modelos, con autenticación Bearer Token. Obtenga la clave en la página de gestión de API Keys.
La consulta funciona incluso con saldo 0. No se comprueba el saldo, pero sí el estado y la caducidad de la clave, la lista de IP permitidas y el estado de la cuenta.

Endpoints

Ambos endpoints tienen la misma función y admiten CORS. Proteja su API Key y no la exponga en código frontend público.

Parámetros de solicitud

Todos los parámetros se envían en la cadena de consulta de la URL.
integer | string
Inicio del período, incluido. Admite un timestamp Unix en segundos o una cadena RFC3339 con zona horaria, como 2026-09-01T00:00:00+08:00.Si se omite, se usan 24 horas antes de end. Los timestamps están en segundos, no milisegundos.
integer | string
Fin del período, excluido. Mismo formato que start; si se omite, se usa la hora actual.Debe ser posterior a start, y end - start no puede superar 31 días.
string
Nombre del modelo. Si se omite, se incluyen todos los modelos. Separe varios modelos con comas; máximo 50.Coincidencia exacta sin distinguir mayúsculas y minúsculas. No admite comodines.Ejemplo: gpt-5.6-luna,sora-2
string
predeterminado:"none"
Agrupación:
  • none: solo el total; items es un array vacío
  • model: por modelo
  • date: por día natural
  • model,date: por modelo y día natural
string
predeterminado:"Asia/Shanghai"
Nombre de zona horaria IANA. Predeterminado: Asia/Shanghai.Solo afecta a los límites de los días cuando group_by incluye date; no cambia los instantes de inicio y fin. Las horas RFC3339 se interpretan según su propia zona horaria.
string
predeterminado:"key"
Ámbito de las estadísticas:
  • key: solo la API Key actual (predeterminado)
  • account: todas las API Keys de la cuenta a la que pertenece la clave actual
El intervalo es [start, end): incluye el inicio y excluye el final. Use el mismo instante para el end de la consulta anterior y el start de la siguiente para evitar duplicar el límite.Al construir la URL manualmente, codifique el + de RFC3339 como %2B. cURL --data-urlencode, Python params y JavaScript URLSearchParams en los ejemplos lo hacen automáticamente.

Ejemplos de solicitud

Gastos de la API Key actual en las últimas 24 horas

Sin parámetros de consulta se utilizan el período, ámbito y agrupación predeterminados.

Gastos diarios de toda la cuenta para modelos concretos

Consultar los gastos del 11 al 18 de septiembre de 2026, hora de Pekín, sin incluir el 18 de septiembre.

Agrupar por modelo y día natural

Cada elemento de items contiene tanto model como date con esta agrupación.

Campos de respuesta

boolean
Resultado de la consulta: true si tiene éxito, false si hay un error al consultar el uso.
object
Si tiene éxito, devuelve el ámbito, el total y los detalles agrupados.
data.total y data.items[] comparten estos campos estadísticos:
object
En errores de consulta de uso, contiene code, message y type, donde type es usage_query_error. Los errores de autenticación 401 / 403 los devuelve la capa de autenticación.

Límites y caché

  • Máximo 60 consultas por minuto por API Key; también se aplican los límites globales de la API
  • Los resultados con los mismos parámetros se almacenan en caché durante 60 segundos; la cabecera X-Usage-Cache es hit o miss
  • Los gastos suelen estar disponibles en 1 segundo, pero el último minuto puede estar incompleto y la caché puede añadir retrasos
  • Se recomienda un intervalo mínimo de 1 minuto; no usar como notificación de cobro en tiempo real

Criterios de contabilización

  • Basado en llamadas facturadas correctamente, con los mismos datos que el panel del sitio web
  • Se excluyen llamadas fallidas y tareas reembolsadas tras un fallo; no es necesario compensarlas manualmente. Los lotes de imágenes parcialmente completados se cobran según las imágenes realmente entregadas
  • Se usa el momento de contabilización del cobro. Las tareas asíncronas de imagen y vídeo se contabilizan al finalizar, no al enviarse; las que cruzan la medianoche pertenecen al día de finalización
  • Una API Key recreada tras eliminarla es una clave nueva. Su consulta scope=key no incluye el historial de la anterior
  • Los ajustes manuales de saldo no son gastos de llamadas y se excluyen
  • Están disponibles los datos posteriores al 27 de abril de 2026

Gestión de errores

503 usage_unavailable no devuelve importes. Significa que la consulta no está disponible, no que los gastos sean 0. No convierta respuestas fallidas en importes cero ni sobrescriba un resultado anterior correcto.

Comparación con otros endpoints

Para el saldo restante, use Consultar saldo del token o Consultar saldo del usuario.