> ## Documentation Index > Fetch the complete documentation index at: https://gccai.heqingsong.uk/llms.txt > Use this file to discover all available pages before exploring further. # Consultar gastos y uso > - Consultar gastos y estadísticas de llamadas en un período - Filtrar por modelo y agrupar por modelo o día natural - Consultar la API Key actual o toda la cuenta - Obtener importes en USD, créditos, llamadas y tokens 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. ```bash cURL theme={null} curl --get 'https://gccai.heqingsong.uk/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=2026-09-01T00:00:00+08:00' \ --data-urlencode 'end=2026-09-08T00:00:00+08:00' \ --data-urlencode 'group_by=model' ``` ```python Python theme={null} import requests response = requests.get( "https://gccai.heqingsong.uk/v1/usage", headers={"Authorization": "Bearer "}, params={ "start": "2026-09-01T00:00:00+08:00", "end": "2026-09-08T00:00:00+08:00", "group_by": "model", }, timeout=30, ) payload = response.json() if not response.ok or not payload.get("success"): message = payload.get("error", {}).get("message", "Error al consultar el uso") raise RuntimeError(f"HTTP {response.status_code}: {message}") print(payload["data"]["total"]) print(payload["data"]["items"]) ``` ```javascript JavaScript theme={null} const url = new URL("https://gccai.heqingsong.uk/v1/usage"); url.search = new URLSearchParams({ start: "2026-09-01T00:00:00+08:00", end: "2026-09-08T00:00:00+08:00", group_by: "model", }).toString(); const response = await fetch(url, { headers: { Authorization: "Bearer " }, }); const payload = await response.json(); if (!response.ok || !payload.success) { throw new Error( `HTTP ${response.status}: ${payload.error?.message ?? "Error al consultar el uso"}`, ); } console.log(payload.data.total); console.log(payload.data.items); ``` ```json 200 theme={null} { "success": true, "data": { "scope": "key", "start": 1788192000, "end": 1788796800, "tz": "Asia/Shanghai", "group_by": "model", "total": { "amount_usd": 12.3456, "credits": 123.456, "requests": 1834, "prompt_tokens": 902311, "completion_tokens": 215044 }, "items": [ { "model": "gpt-5.6-luna", "amount_usd": 9.1271, "credits": 91.271, "requests": 1520, "prompt_tokens": 880120, "completion_tokens": 201300 }, { "model": "sora-2", "amount_usd": 3.2185, "credits": 32.185, "requests": 314, "prompt_tokens": 22191, "completion_tokens": 13744 } ] } } ``` ```json 400 theme={null} { "success": false, "error": { "code": "range_too_large", "message": "Time range must not exceed 31 days.", "type": "usage_query_error" } } ``` ## Autenticación **Authorization** `string` *required* 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](https://gccai.heqingsong.uk/keys). ``` Authorization: Bearer YOUR_API_KEY ``` > [!NOTE] > > 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 ```text theme={null} GET /v1/usage GET /usage ``` 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. **start** `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. **end** `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. **model** `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` **group\_by** `string` (default: 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 **tz** `string` (default: 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. **scope** `string` (default: 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 > [!NOTE] > > 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. ```bash theme={null} curl 'https://gccai.heqingsong.uk/v1/usage' \ --header 'Authorization: Bearer ' ``` ### 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. ```bash theme={null} curl --get 'https://gccai.heqingsong.uk/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=1789056000' \ --data-urlencode 'end=1789660800' \ --data-urlencode 'model=gpt-5.6-luna' \ --data-urlencode 'group_by=date' \ --data-urlencode 'scope=account' \ --data-urlencode 'tz=Asia/Shanghai' ``` ### Agrupar por modelo y día natural ```bash theme={null} curl --get 'https://gccai.heqingsong.uk/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=2026-09-01T00:00:00+08:00' \ --data-urlencode 'end=2026-09-08T00:00:00+08:00' \ --data-urlencode 'model=gpt-5.6-luna,sora-2' \ --data-urlencode 'group_by=model,date' \ --data-urlencode 'tz=Asia/Shanghai' ``` Cada elemento de `items` contiene tanto `model` como `date` con esta agrupación. ## Campos de respuesta **success** `boolean` Resultado de la consulta: `true` si tiene éxito, `false` si hay un error al consultar el uso. **data** `object` Si tiene éxito, devuelve el ámbito, el total y los detalles agrupados. **Propiedades de data** **scope** `string` Ámbito: `key` o `account`. **start** `integer` Inicio efectivo como timestamp Unix en segundos, incluido. **end** `integer` Fin efectivo como timestamp Unix en segundos, excluido. **tz** `string` Zona horaria para la agrupación por día natural. **group\_by** `string` Agrupación: `none`, `model`, `date` o `model,date`. **total** `object` Total del intervalo consultado. Consulte los campos estadísticos en la tabla siguiente. **items** `object[]` Detalles agrupados en orden descendente de `amount_usd`. Array vacío si `group_by=none`. Cada elemento contiene los campos estadísticos de la tabla siguiente. * Si `group_by` incluye `model`, el elemento contiene `model` * Si `group_by` incluye `date`, el elemento contiene `date` en formato `YYYY-MM-DD`; los días se delimitan según `tz` `data.total` y `data.items[]` comparten estos campos estadísticos: | Campo | Tipo | Descripción | | - | - | - | | `amount_usd` | number | Importe en USD, redondeado a 6 decimales | | `credits` | number | Créditos del servicio: `amount_usd × 10`, la misma unidad que en el sitio web | | `requests` | integer | Número de llamadas facturadas correctamente | | `prompt_tokens` | integer | Tokens de entrada; normalmente 0 para modelos de imagen y vídeo facturados por llamada o segundo | | `completion_tokens` | integer | Tokens de salida; normalmente 0 para modelos de imagen y vídeo facturados por llamada o segundo | **error** `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 | Estado HTTP | `error.code` | Descripción | | - | - | - | | 400 | `invalid_start` / `invalid_end` | Formato de inicio o fin no válido | | 400 | `invalid_range` | `end` no es posterior a `start` | | 400 | `range_too_large` | Más de 31 días; divida el período en varias consultas | | 400 | `invalid_tz` | Zona horaria IANA desconocida | | 400 | `invalid_group_by` | Agrupación no válida | | 400 | `invalid_scope` | Ámbito no válido | | 400 | `too_many_models` | Más de 50 modelos | | 401 / 403 | — | API Key no válida o caducada, IP no permitida o cuenta desactivada | | 429 | — | Más de 60 consultas por clave por minuto o límite global de la API | | 503 | `usage_unavailable` | Datos temporalmente no disponibles; inténtelo más tarde | > [!WARNING] > > `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 | Endpoint | Función | | - | - | | `GET /v1/dashboard/billing/usage` | Solo gastos acumulados; sin filtros por modelo o período | | `POST /v1/logs/export` | Exportación asíncrona de detalles de llamadas (CSV / XLSX); debe agregarlos usted | | `GET /v1/usage` | Consulta por período y modelo con devolución directa del total y los detalles agrupados | Para el saldo restante, use [Consultar saldo del token](https://gccai.heqingsong.uk/es/api-reference/account/token-balance.md) o [Consultar saldo del usuario](https://gccai.heqingsong.uk/es/api-reference/account/user-balance.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.