API de uso

Lista las tareas de API finalizadas de tu equipo y los créditos que cada una consumió, para exportaciones de facturación e informes de costos.

Para llamar a este endpoint, usa una clave de API de un miembro activo de un equipo Studio o Enterprise. Cualquier miembro puede llamarlo, no solo los propietarios y administradores. Con cualquier otra clave de API, la solicitud devuelve 403.

GET/openapi/v1/usage/tasks

Listar registros de uso

Devuelve una página de los registros de uso de tu equipo, con los más recientes primero de forma predeterminada. Sin start_time ni end_time, los registros cubren los últimos 30 días. Llamar a este endpoint es gratuito.

Los registros incluyen estas tareas:

Tareas de API que finalizaron como SUCCEEDED o FAILED
Tareas de todos los miembros actuales del equipo, desde cualquiera de sus claves de API
Tareas que eliminaste, y tareas cuyos archivos han expirado

Los registros excluyen estas tareas:

Tareas que aún están PENDING o IN_PROGRESS, y tareas CANCELED
Tareas de personas que han dejado el equipo
Tareas de Creative Lab
Tareas que ejecutaron los agentes de IA de Meshy
Trabajo realizado en la aplicación web de Meshy

Una tarea aparece en los registros solo después de finalizar, dentro de la ventana de su created_at. Meshy cobra créditos al crear una tarea, por lo que una tarea que aún se está ejecutando no aparece en los registros. Antes de conciliar los registros con tu saldo de créditos, vuelve a consultar las ventanas recientes, o exporta después de un breve retraso.

Si tu equipo tiene un período de retención de datos, la ventana no comienza antes de lo que ese período permite.

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",
    "metadata": {
      "user": "alex@example.com",
      "team": "fab"
    }
  },
  {
    "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",
    "metadata": {}
  }
]

Parámetros

Name
page_num
Type
integer
predeterminado 1
Description
La página a devolver, de 1 a 255. Un valor superior a 255 devuelve 400. Una ventana contiene como máximo 255 páginas, así que divide una exportación grande en ventanas más cortas.
Name
page_size
Type
integer
predeterminado 10
Description
Número de registros por página, de 1 a 100. Un valor entre 101 y 255 devuelve 100 registros, y un valor superior a 255 devuelve 400.
Name
sort_by
Type
string
predeterminado -created_at
Description
El orden de clasificación.
Valores disponibles:
- +created_at: más antiguos primero
- -created_at: más recientes primero
En una URL, escribe + como %2B. De lo contrario, el + se interpreta como un espacio, y la solicitud devuelve 400.
Name
start_time
Type
string
Description
El inicio de la ventana, como una marca de tiempo RFC 3339, por ejemplo 2026-08-01T00:00:00Z. Los registros incluyen tareas creadas en o después de este momento. Omítelo para que la ventana comience 30 días antes de end_time.
La ventana puede abarcar como máximo 366 días. Una ventana más larga devuelve 400, así que divide una exportación más larga en varias ventanas.
Name
end_time
Type
string
Description
El final de la ventana, como una marca de tiempo RFC 3339. Los registros incluyen tareas creadas antes de este momento. Omítelo para que la ventana termine en el momento de tu solicitud.
Name
endpoints
Type
string
Description
Una lista separada por comas de los endpoints a incluir, con los mismos nombres que el campo endpoint. Omítelo para incluir todos los endpoints. Un nombre desconocido devuelve 400.
Valores disponibles:
- text-to-3d: todas las tareas de Texto a 3D, preview y refine
- text-to-3d-preview: solo tareas de preview
- text-to-3d-refine: solo tareas de 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
Name
status
Type
string
Description
El estado a incluir, SUCCEEDED o FAILED. Omítelo para incluir ambos. Cualquier otro valor devuelve 400.

Devuelve

Devuelve un array de registros de uso. El array está vacío cuando no hay registros que coincidan.

Modos de fallo

Name
400 - Bad Request
Description
Un parámetro no es válido, y el mensaje de error indica cuál. Corrige el parámetro y vuelve a enviar la solicitud.
Name
401 - Unauthorized
Description
Falta la clave de API o no es válida. Verifica el encabezado Authorization.
Name
403 - Forbidden
Description
La cuenta de la clave de API no es un miembro activo de un equipo Studio o Enterprise. El mensaje es This endpoint is available on Studio and Enterprise plans. Usa una clave de API de un miembro de un equipo Studio o Enterprise.
Name
429 - Too Many Requests
Description
Enviaste demasiadas solicitudes. Espera el número de segundos indicado en Retry-After, y vuelve a intentarlo.

Objeto de registro de uso

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",
  "metadata": {
    "user": "alex@example.com",
    "team": "fab"
  }
}

Name
task_id
Type
string
Description
El ID de la tarea, el mismo ID que devolvió el endpoint que la creó. Para obtener la tarea en sí, con sus URL de salida, envía el ID a la ruta de obtención de ese endpoint, por ejemplo GET /openapi/v1/image-to-3d/{task_id} para un registro de image-to-3d.
Name
endpoint
Type
string
Description
El endpoint en el que se ejecutó la tarea, por ejemplo image-to-3d o rig. Una tarea de Texto a 3D muestra su etapa, text-to-3d-preview o text-to-3d-refine.
Los registros más antiguos pueden tener nombres de endpoints retirados, que el filtro endpoints no acepta.
Name
status
Type
string
Description
El estado final de la tarea, SUCCEEDED o FAILED.
Name
created_at
Type
timestamp
Description
Momento en que se creó la tarea, en milisegundos Unix.
Name
finished_at
Type
timestamp
Description
Momento en que finalizó la tarea, en milisegundos Unix. null si la tarea no tiene hora de finalización.
Name
consumed_credits
Type
integer
Description
Número de créditos que consumió la tarea, después de los reembolsos. 0 para una tarea fallida, porque Meshy la reembolsa, y para una tarea gratuita como Analizar imprimibilidad.
Name
api_key_name
Type
string
Description
El nombre de la clave de API que ejecutó la tarea. Para una tarea ejecutada con un inicio de sesión de aplicación, es el nombre de la aplicación, por ejemplo Meshy CLI.
Es una cadena vacía en algunos casos, por ejemplo:
- La tarea nunca se cobró, como una tarea de Analizar imprimibilidad, que es gratuita.
- La clave de API ha sido eliminada.
- La clave de API se creó en los últimos minutos.
Name
api_key_suffix
Type
string
Description
Los últimos cuatro caracteres de esa clave de API, para distinguir claves con el mismo nombre. Una cadena vacía siempre que api_key_name esté vacío, y para los inicios de sesión de aplicación como el Meshy CLI.
Name
metadata
Type
object
Description
Las etiquetas enviadas en el encabezado X-Meshy-Metadata al crear la tarea. {} si no hay ninguna. Consulta Metadata.