curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>' \
--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'
import requests
response = requests.get(
"https://api.apimart.ai/v1/usage",
headers={"Authorization": "Bearer <token>"},
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"])
const url = new URL("https://api.apimart.ai/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 <token>" },
});
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);
{
"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
}
]
}
}
{
"success": false,
"error": {
"code": "range_too_large",
"message": "Time range must not exceed 31 days.",
"type": "usage_query_error"
}
}
Gestión de cuenta
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
GET
/
v1
/
usage
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>' \
--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'
import requests
response = requests.get(
"https://api.apimart.ai/v1/usage",
headers={"Authorization": "Bearer <token>"},
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"])
const url = new URL("https://api.apimart.ai/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 <token>" },
});
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);
{
"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
}
]
}
}
{
"success": false,
"error": {
"code": "range_too_large",
"message": "Time range must not exceed 31 days.",
"type": "usage_query_error"
}
}
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.
Ambos endpoints tienen la misma función y admiten CORS. Proteja su API Key y no la exponga en código frontend público.
Cada elemento de
Para el saldo restante, use Consultar saldo del token o Consultar saldo del usuario.
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>' \
--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'
import requests
response = requests.get(
"https://api.apimart.ai/v1/usage",
headers={"Authorization": "Bearer <token>"},
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"])
const url = new URL("https://api.apimart.ai/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 <token>" },
});
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);
{
"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
}
]
}
}
{
"success": false,
"error": {
"code": "range_too_large",
"message": "Time range must not exceed 31 days.",
"type": "usage_query_error"
}
}
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.
Authorization: Bearer YOUR_API_KEY
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
GET /v1/usage
GET /usage
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-2string
predeterminado:"none"
Agrupación:
none: solo el total;itemses un array vacíomodel: por modelodate: por día naturalmodel,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.curl 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>'
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.curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>' \
--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
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer <token>' \
--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'
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.
Mostrar Propiedades de data
Mostrar Propiedades de data
string
Ámbito:
key o account.integer
Inicio efectivo como timestamp Unix en segundos, incluido.
integer
Fin efectivo como timestamp Unix en segundos, excluido.
string
Zona horaria para la agrupación por día natural.
string
Agrupación:
none, model, date o model,date.object
Total del intervalo consultado. Consulte los campos estadísticos en la tabla siguiente.
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_byincluyemodel, el elemento contienemodel - Si
group_byincluyedate, el elemento contienedateen formatoYYYY-MM-DD; los días se delimitan segúntz
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 |
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
60consultas 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
60segundos; la cabeceraX-Usage-Cacheeshitomiss - 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=keyno 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 |
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 |