API de Uso

La API de Uso devuelve las tareas históricas de la API de tu equipo junto con los créditos que consumió cada una. 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

List Usage Records

Devuelve una página de las tareas de la API del equipo, empezando por las más recientes. Sin un rango de tiempo explícito, la respuesta cubre 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 del tamaño de página. El máximo permitido es 100 elementos.
Name
sort_by
Type
string
predeterminado -created_at
Description
Campo por el que 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 de created_at, como una marca de tiempo RFC 3339 (p. ej. 2026-08-01T00:00:00Z). El valor predeterminado es 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 de created_at, como una marca de tiempo RFC 3339. El valor predeterminado es la hora actual.
Name
endpoints
Type
string
Description
Lista de nombres de endpoints a incluir, separados por comas. 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 — donde text-to-3d es un término general que cubre tanto la fase de vista previa como la de refinamiento. Omítelo para incluir todos los endpoints.
Name
status
Type
string
Description
Filtra por el estado final 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 final. Los créditos se cobran cuando se crea una tarea, por lo que una tarea que todavía se está ejecutando cuando exportas aún no aparece 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"
  }
]

The Usage Record Object

Name
task_id
Type
string
Description
ID de la tarea que factura este registro; el mismo ID que devolvió el endpoint que la creó. Para obtener la tarea en sí (incluyendo su modelo de salida o las URL de imagen, resignadas 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 final 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 una hora de finalización.
Name
consumed_credits
Type
integer
Description
Créditos consumidos por esta tarea. Devuelve 0 para las 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 disponible incluso para claves revocadas, de modo que el gasto histórico se pueda seguir atribuyendo tras 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"
}