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 temporelle, point de terminaison ou statut, et parcourez les résultats page par page pour les exporter en masse.

Disponibilité. La clé API doit appartenir à une équipe Studio ou Enterprise ; les clés d'un 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, les plus récentes en premier. Sans plage temporelle 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 selon lequel effectuer le tri.
Valeurs disponibles :
- +created_at : Trier par date de création par ordre croissant.
- -created_at : Trier par date de création par 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). La valeur par défaut est 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. La valeur par défaut est l'heure actuelle.
Name
endpoints
Type
string
Description
Liste de noms de points de terminaison séparés par des virgules, à inclure. 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, print-split — 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 terminal 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 terminal. 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 — retirez 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 limite de leur 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 que cet enregistrement facture — le même ID que celui renvoyé par le point de terminaison à l'origine de la création. Pour récupérer la tâche elle-même (y compris son modèle de sortie ou ses URL d'image, re-signé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 terminal de la tâche : SUCCEEDED ou FAILED.
Name
created_at
Type
timestamp
Description
Horodatage de la création de la tâche, en millisecondes.
Name
finished_at
Type
timestamp
Description
Horodatage de l'achèvement, en millisecondes. null si la tâche ne comporte pas d'heure d'achèvement.
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, permettant de 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"
}