API d'utilisation

L'API d'utilisation renvoie l'historique des tâches API de votre équipe ainsi que les crédits que chacune a consommés. Filtrez par plage horaire, point de terminaison ou statut, et parcourez les résultats page par page pour un export en masse.

Disponibilité. La clé API doit appartenir à une équipe Studio ou Enterprise ; les clés de tout autre forfait, ou sans équipe associée, reçoivent une erreur 403.

GET/openapi/v1/usage/tasks

Lister les enregistrements d'utilisation

Renvoie une page des tâches API de l'équipe, des plus récentes aux plus anciennes. Sans plage horaire explicite, la réponse couvre les 30 derniers jours.

Paramètres

Name
page_num
Type
integer
défaut 1
Description
Numéro de page pour la pagination.
Name
page_size
Type
integer
défaut 10
Description
Limite de taille de page. Le maximum autorisé est de 100 éléments.
Name
sort_by
Type
string
défaut -created_at
Description
Champ à utiliser pour le tri.
Valeurs disponibles :
- +created_at : trier par date de création dans l'ordre croissant.
- -created_at : trier par date de création dans l'ordre décroissant.
Name
start_time
Type
string
Description
Début de la plage created_at, sous forme d'horodatage RFC 3339 (par ex. 2026-08-01T00:00:00Z). Par défaut, 30 jours avant end_time. La plage peut couvrir au maximum 1 an — pour des exports plus volumineux, parcourez des plages consécutives.
Name
end_time
Type
string
Description
Fin de la plage created_at, sous forme d'horodatage RFC 3339. Par défaut, l'heure actuelle.
Name
endpoints
Type
string
Description
Liste de noms de points de terminaison à inclure, séparés par des virgules. Accepte les mêmes valeurs que celles portées par le champ de réponse 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 — où text-to-3d est une catégorie englobant à la fois les phases preview et refine. Omettez ce paramètre pour inclure tous les points de terminaison.
Name
status
Type
string
Description
Filtrer par statut final de la tâche : SUCCEEDED ou FAILED. Omettez ce paramètre pour inclure les deux.

Retours

Renvoie une liste paginée d'objets enregistrement d'utilisation.

Les enregistrements couvrent les tâches ayant atteint un statut final. Les crédits sont débités à la création d'une tâche, donc une tâche encore en cours d'exécution au moment de votre export n'apparaît pas encore dans les résultats de cette plage — récupérez à nouveau les plages récentes (ou exportez avec un léger délai) si vos totaux doivent correspondre exactement à votre solde de crédits.

Les équipes disposant d'une politique de conservation des données personnalisée reçoivent les enregistrements dans la fenêtre de conservation configurée.

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"
  }
]

L'objet enregistrement d'utilisation

Name
task_id
Type
string
Description
ID de la tâche facturée par cet enregistrement — le même ID que celui renvoyé par le point de terminaison qui a créé la tâche. Pour récupérer la tâche elle-même (y compris son modèle de sortie ou les URL d'image, resignées à chaque lecture), transmettez-le au point de terminaison de récupération correspondant, par ex. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Le point de terminaison sur lequel la tâche a été exécutée, par ex. image-to-3d ou text-to-3d-refine. Les tâches Texte en 3D indiquent leur phase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Statut final de la tâche : SUCCEEDED ou FAILED.
Name
created_at
Type
timestamp
Description
Horodatage de création de la tâche, en millisecondes.
Name
finished_at
Type
timestamp
Description
Horodatage de fin, en millisecondes. null si la tâche ne comporte pas d'heure de fin.
Name
consumed_credits
Type
integer
Description
Crédits consommés par cette tâche. Renvoie 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).
Name
api_key_name
Type
string
Description
Nom d'affichage de la clé API ayant exécuté la tâche. Reste renseigné pour les clés révoquées, afin que les dépenses historiques restent attribuables après rotation des clés.
Name
api_key_suffix
Type
string
Description
Les quatre derniers caractères de cette clé API, pour distinguer des clés portant le même nom.

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"
}