API d'utilisation

L'API d'utilisation renvoie l'historique des tâches API de votre équipe ainsi que les crédits consommés par chacune d'elles. Filtrez par fenêtre 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 associées à tout autre forfait, ou sans équipe, reçoivent un 403.

GET/openapi/v1/usage/tasks

Lister les enregistrements d'utilisation

Renvoie une page des tâches API de l'équipe, de la plus récente à la plus ancienne. 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 utilisé 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 fenêtre created_at, sous forme d'horodatage RFC 3339 (par ex. 2026-08-01T00:00:00Z). Par défaut, 30 jours avant end_time. La fenêtre peut couvrir au maximum 1 an — pour des exports plus volumineux, parcourez des fenêtres consécutives page par page.
Name
end_time
Type
string
Description
Fin de la fenêtre 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 englobante couvrant à 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.

Retourne

Retourne 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 fenêtre — récupérez à nouveau les fenêtres 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 correspondant à 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 facturée par cet enregistrement — le même ID que celui renvoyé par le point de terminaison créateur. Pour récupérer la tâche elle-même (y compris son modèle de sortie ou ses URL d'images, 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 s'est 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 d'exécution, en millisecondes. null si la tâche ne comporte pas d'horodatage 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 une rotation de clé.
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"
}