API Usage

Listez les tâches API terminées de votre équipe et les crédits que chacune a consommés, pour les exports de facturation et les rapports de coûts.

Pour appeler ce point de terminaison, utilisez une clé API d'un membre actif d'une équipe Studio ou Enterprise. N'importe quel membre peut l'appeler, pas seulement les propriétaires et administrateurs. Avec toute autre clé API, la requête renvoie 403.

GET/openapi/v1/usage/tasks

Lister les enregistrements d'utilisation

Renvoie une page des enregistrements d'utilisation de votre équipe, les plus récents en premier par défaut. Sans start_time ni end_time, les enregistrements couvrent les 30 derniers jours. Appeler ce point de terminaison est gratuit.

Les enregistrements incluent ces tâches :

Les tâches API terminées avec le statut SUCCEEDED ou FAILED
Les tâches de chaque membre actuel de l'équipe, depuis n'importe laquelle de leurs clés API
Les tâches que vous avez supprimées, et les tâches dont les fichiers ont expiré

Les enregistrements excluent ces tâches :

Les tâches encore PENDING ou IN_PROGRESS, et les tâches CANCELED
Les tâches des personnes ayant quitté l'équipe
Les tâches Creative Lab
Les tâches exécutées par les agents IA de Meshy
Le travail effectué dans l'application web Meshy

Une tâche n'apparaît dans les enregistrements qu'une fois terminée, dans la fenêtre correspondant à son created_at. Meshy facture des crédits à la création d'une tâche, donc une tâche encore en cours d'exécution est absente des enregistrements. Avant de réconcilier les enregistrements avec votre solde de crédits, récupérez à nouveau les fenêtres récentes, ou exportez après un court délai.

Si votre équipe dispose d'une période de rétention des données, la fenêtre ne peut pas commencer avant le début de cette période.

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

Paramètres

Name
page_num
Type
integer
défaut 1
Description
La page à renvoyer, de 1 à 255. Une valeur supérieure à 255 renvoie 400. Une fenêtre contient au maximum 255 pages, donc divisez un export volumineux en fenêtres plus courtes.
Name
page_size
Type
integer
défaut 10
Description
Nombre d'enregistrements par page, de 1 à 100. Une valeur comprise entre 101 et 255 renvoie 100 enregistrements, et une valeur supérieure à 255 renvoie 400.
Name
sort_by
Type
string
défaut -created_at
Description
L'ordre de tri.
Valeurs disponibles :
- +created_at : du plus ancien au plus récent
- -created_at : du plus récent au plus ancien
Dans une URL, écrivez + sous la forme %2B. Sinon, le + est interprété comme un espace, et la requête renvoie 400.
Name
start_time
Type
string
Description
Le début de la fenêtre, sous forme d'horodatage RFC 3339, par exemple 2026-08-01T00:00:00Z. Les enregistrements incluent les tâches créées à partir de cette heure ou après. Omettez-le pour faire commencer la fenêtre 30 jours avant end_time.
La fenêtre peut couvrir au maximum 366 jours. Une fenêtre plus longue renvoie 400, donc divisez un export plus long en plusieurs fenêtres.
Name
end_time
Type
string
Description
La fin de la fenêtre, sous forme d'horodatage RFC 3339. Les enregistrements incluent les tâches créées avant cette heure. Omettez-le pour terminer la fenêtre au moment de votre requête.
Name
endpoints
Type
string
Description
Une liste de points de terminaison séparés par des virgules à inclure, selon les mêmes noms que le champ endpoint. Omettez-le pour inclure tous les points de terminaison. Un nom inconnu renvoie 400.
Valeurs disponibles :
- text-to-3d : toutes les tâches Texte en 3D, preview et refine
- text-to-3d-preview : tâches preview uniquement
- text-to-3d-refine : tâches refine uniquement
- 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
Le statut à inclure, SUCCEEDED ou FAILED. Omettez-le pour inclure les deux. Toute autre valeur renvoie 400.

Retours

Renvoie un tableau d'enregistrements d'utilisation. Le tableau est vide lorsqu'aucun enregistrement ne correspond.

Modes d'échec

Name
400 - Bad Request
Description
Un paramètre est invalide, et le message d'erreur indique lequel. Corrigez le paramètre, puis renvoyez la requête.
Name
401 - Unauthorized
Description
La clé API est manquante ou invalide. Vérifiez l'en-tête Authorization.
Name
403 - Forbidden
Description
Le compte de la clé API n'est pas un membre actif d'une équipe Studio ou Enterprise. Le message est This endpoint is available on Studio and Enterprise plans. Utilisez une clé API d'un membre d'une équipe Studio ou Enterprise.
Name
429 - Too Many Requests
Description
Vous avez envoyé trop de requêtes. Attendez le nombre de secondes indiqué dans Retry-After, puis réessayez.

Objet enregistrement d'utilisation

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
L'ID de la tâche, le même ID que celui renvoyé par le point de terminaison créateur. Pour obtenir la tâche elle-même, avec ses URL de sortie, envoyez l'ID à la route de récupération de ce point de terminaison, par exemple GET /openapi/v1/image-to-3d/{task_id} pour un enregistrement image-to-3d.
Name
endpoint
Type
string
Description
Le point de terminaison sur lequel la tâche a été exécutée, par exemple image-to-3d ou rig. Une tâche Texte en 3D affiche son étape, text-to-3d-preview ou text-to-3d-refine.
Les enregistrements plus anciens peuvent avoir des noms de points de terminaison retirés, que le filtre endpoints n'accepte pas.
Name
status
Type
string
Description
Le statut final de la tâche, SUCCEEDED ou FAILED.
Name
created_at
Type
timestamp
Description
Heure de création de la tâche, en millisecondes Unix.
Name
finished_at
Type
timestamp
Description
Heure de fin de la tâche, en millisecondes Unix. null si la tâche n'a pas d'heure de fin.
Name
consumed_credits
Type
integer
Description
Nombre de crédits consommés par la tâche, après remboursements. 0 pour une tâche échouée, car Meshy la rembourse, et pour une tâche gratuite telle qu'Analyser l'imprimabilité.
Name
api_key_name
Type
string
Description
Le nom de la clé API qui a exécuté la tâche. Pour une tâche exécutée avec une connexion à une application, il s'agit du nom de l'application, par exemple Meshy CLI.
C'est une chaîne vide dans certains cas, par exemple :
- La tâche n'a jamais été facturée, comme une tâche Analyser l'imprimabilité, qui est gratuite.
- La clé API a été supprimée.
- La clé API a été créée il y a quelques minutes.
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. Une chaîne vide chaque fois que api_key_name est vide, et pour les connexions d'application telles que Meshy CLI.
Name
metadata
Type
object
Description
Les étiquettes envoyées dans l'en-tête X-Meshy-Metadata lors de la création de la tâche. {} si aucune. Voir Metadata.