API de Uso

La API de Uso devuelve las tareas históricas de la API de tu equipo junto con los créditos que cada una consumió. Filtra por ventana de tiempo, endpoint o estado, y navega por los resultados para exportarlos en bloque.

Disponibilidad. La clave de API debe pertenecer a un equipo Studio o Enterprise; las claves de cualquier otro plan, o sin equipo, reciben un 403.

GET/openapi/v1/usage/tasks

Listar Registros de Uso

Devuelve una página de las tareas de la API del equipo, de más reciente a más antigua. Sin un rango de tiempo explícito, la respuesta abarca los últimos 30 días.

Parámetros

Name
page_num
Type
integer
predeterminado 1
Description
Número de página para la paginación.
Name
page_size
Type
integer
predeterminado 10
Description
Límite de tamaño de página. El máximo permitido es 100 elementos.
Name
sort_by
Type
string
predeterminado -created_at
Description
Campo por el cual ordenar.
Valores disponibles:
- +created_at: Ordenar por hora de creación en orden ascendente.
- -created_at: Ordenar por hora de creación en orden descendente.
Name
start_time
Type
string
Description
Inicio de la ventana created_at, como marca de tiempo RFC 3339 (p. ej. 2026-08-01T00:00:00Z). Por defecto, 30 días antes de end_time. La ventana puede abarcar como máximo 1 año — para exportaciones más grandes, navega por ventanas consecutivas.
Name
end_time
Type
string
Description
Fin de la ventana created_at, como marca de tiempo RFC 3339. Por defecto, la hora actual.
Name
endpoints
Type
string
Description
Lista separada por comas de nombres de endpoints a incluir. Acepta los mismos valores que lleva el campo de respuesta endpoint — text-to-3d, text-to-3d-preview, text-to-3d-refine, image-to-3d, multi-image-to-3d, retexture, remesh, convert, resize, uv-unwrap, rig, animate, text-to-motion, text-to-image, image-to-image, print-multi-color, print-repair, print-analyze, print-split — donde text-to-3d es un término general que cubre tanto la fase de vista previa como la de refine. Omítelo para incluir todos los endpoints.
Name
status
Type
string
Description
Filtra por estado terminal de la tarea: SUCCEEDED o FAILED. Omítelo para incluir ambos.

Devuelve

Devuelve una lista paginada de Objetos de Registro de Uso.

Los registros cubren tareas que han alcanzado un estado terminal. Los créditos se cobran cuando se crea una tarea, por lo que una tarea que aún está en ejecución cuando exportas no está todavía en los resultados de esa ventana — vuelve a extraer las ventanas recientes (o exporta con un pequeño retraso) si tus totales deben coincidir exactamente con tu saldo de créditos.

Los equipos con una política de retención de datos personalizada reciben registros dentro de su ventana de retención configurada.

Request

GET

/openapi/v1/usage/tasks

curl "https://api.meshy.ai/openapi/v1/usage/tasks?page_size=50&start_time=2026-08-01T00:00:00Z&end_time=2026-09-01T00:00:00Z" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "endpoint": "image-to-3d",
    "status": "SUCCEEDED",
    "created_at": 1755787000000,
    "finished_at": 1755787045000,
    "consumed_credits": 20,
    "api_key_name": "production",
    "api_key_suffix": "a1b2"
  },
  {
    "task_id": "018a210d-1c22-7e0f-9d3a-4a5b6c7d8e9f",
    "endpoint": "text-to-3d-refine",
    "status": "FAILED",
    "created_at": 1755786000000,
    "finished_at": 1755786030000,
    "consumed_credits": 0,
    "api_key_name": "production",
    "api_key_suffix": "a1b2"
  }
]

El Objeto de Registro de Uso

Name
task_id
Type
string
Description
ID de la tarea que este registro factura — el mismo ID que devolvió el endpoint que la creó. Para obtener la tarea en sí (incluyendo su modelo de salida o URLs de imagen, re-firmadas en cada lectura), pásalo al endpoint de recuperación correspondiente, p. ej. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
El endpoint en el que se ejecutó la tarea, p. ej. image-to-3d o text-to-3d-refine. Las tareas de Texto a 3D informan su fase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Estado terminal de la tarea: SUCCEEDED o FAILED.
Name
created_at
Type
timestamp
Description
Marca de tiempo de creación de la tarea, en milisegundos.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de finalización, en milisegundos. null si la tarea no lleva un tiempo de finalización.
Name
consumed_credits
Type
integer
Description
Créditos consumidos por esta tarea. Devuelve 0 para tareas FAILED (los créditos se reembolsan en caso de fallo).
Name
api_key_name
Type
string
Description
Nombre visible de la clave de API que ejecutó la tarea. Permanece completado para claves revocadas, de modo que el gasto histórico siga siendo atribuible después de la rotación de claves.
Name
api_key_suffix
Type
string
Description
Últimos cuatro caracteres de esa clave de API, para distinguir claves con el mismo nombre.

Example Usage Record Object

{
  "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "endpoint": "image-to-3d",
  "status": "SUCCEEDED",
  "created_at": 1755787000000,
  "finished_at": 1755787045000,
  "consumed_credits": 20,
  "api_key_name": "production",
  "api_key_suffix": "a1b2"
}