lowpoly se retira el 30 oct 2026. meshy-7 se retira como modelo de generación 3D el 31 dic 2026; como modelo de texturas sigue disponible. Cambia de modelo antes de estas fechas para evitar errores en las solicitudes. Ver todas las obsolescencias

API de uso

Lista las tareas de API finalizadas de tu equipo y los créditos que consumió cada una, 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, de forma predeterminada ordenados del más reciente al más antiguo. Sin start_time y end_time, los registros abarcan 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 caducado

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 cuando crea una tarea, así 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 tras un breve retraso.

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

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 antiguo primero
    • -created_at: más reciente 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 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 comenzar la ventana 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 marca de tiempo RFC 3339. Los registros incluyen tareas creadas antes de este momento. Omítelo para finalizar la ventana 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
    • relief
  • 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 ningún registro coincide.

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 envía la solicitud de nuevo.

  • Name
    401 - Unauthorized
    Description

    La clave de API falta o no es válida. Revisa el encabezado Authorization.

  • Name
    403 - Forbidden
    Description

    La cuenta de la clave de API no es 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 la cantidad de segundos indicada en Retry-After, luego reintenta.


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 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 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 usó la tarea, tras 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 app, es el nombre de la app, 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 se ha eliminado.
    • 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 inicios de sesión de app como el Meshy CLI.

  • Name
    metadata
    Type
    object
    Description

    Las etiquetas enviadas en el encabezado X-Meshy-Metadata cuando se creó la tarea. {} si no hay ninguna. Consulta Metadata.