API Usage
Listez les tâches API terminées de votre équipe et les crédits que chacune a consommés, pour vos exports de facturation et vos rapports de coûts.
Pour appeler ce point de terminaison, utilisez une clé API d'un membre actif d'une équipe Studio ou Enterprise. Tout membre peut l'appeler, pas seulement les propriétaires et les administrateurs. Avec toute autre clé API, la requête renvoie 403.
Lister les enregistrements d'utilisation
Renvoie une page des enregistrements d'utilisation de votre équipe, triés par défaut du plus récent au plus ancien. Sans start_time ni end_time, les enregistrements couvrent les 30 derniers jours. L'appel à ce point de terminaison est gratuit.
Les enregistrements incluent ces tâches :
- Les tâches API terminées avec le statut
SUCCEEDEDouFAILED - 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
PENDINGouIN_PROGRESS, et les tâchesCANCELED - Les tâches de personnes ayant quitté l'équipe
- Les tâches du 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 les 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 rapprocher les enregistrements de 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 conservation des données, la fenêtre ne peut pas commencer avant le début autorisé par cette période.
Request
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 à255renvoie400. 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 de101à255renvoie 100 enregistrements, et une valeur supérieure à255renvoie400.
- 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 renvoie400.
- 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 ce paramètre pour faire commencer la fenêtre 30 jours avantend_time.La fenêtre peut couvrir au maximum 366 jours. Une fenêtre plus longue renvoie
400; divisez donc 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 ce paramètre 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, avec les mêmes noms que le champ
endpoint. Omettez ce paramètre pour inclure tous les points de terminaison. Un nom inconnu renvoie400.Valeurs disponibles :
text-to-3d: toutes les tâches Texte en 3D, preview et refinetext-to-3d-preview: tâches preview uniquementtext-to-3d-refine: tâches refine uniquementimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
Le statut à inclure,
SUCCEEDEDouFAILED. Omettez ce paramètre pour inclure les deux. Toute autre valeur renvoie400.
Retours
Renvoie un tableau d'enregistrements d'utilisation. Le tableau est vide si 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.
L'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 cet ID à la route de récupération de ce point de terminaison, par exemple
GET /openapi/v1/image-to-3d/{task_id}pour un enregistrementimage-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-3dourig. Une tâche Texte en 3D affiche son étape,text-to-3d-previewoutext-to-3d-refine.Les enregistrements plus anciens peuvent contenir des noms de points de terminaison retirés, que le filtre
endpointsn'accepte pas.
- Name
- status
- Type
- string
- Description
Le statut final de la tâche,
SUCCEEDEDouFAILED.
- 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.
nullsi la tâche n'a pas d'heure de fin.
- Name
- consumed_credits
- Type
- integer
- Description
Nombre de crédits utilisés par la tâche, après remboursements.
0pour 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 via une connexion d'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 seulement.
- 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_nameest vide, et pour les connexions d'application telles que le Meshy CLI.
- Name
- metadata
- Type
- object
- Description
Les balises envoyées dans l'en-tête
X-Meshy-Metadatalors de la création de la tâche.{}si aucune. Voir Metadata.