Usage API
Elenca i task API completati del tuo team e i crediti usati da ciascuno, per le esportazioni di fatturazione e i report sui costi.
Per chiamare questo endpoint, usa una chiave API di un membro attivo di un team Studio o Enterprise. Qualsiasi membro può chiamarlo, non solo i proprietari e gli amministratori. Con qualsiasi altra chiave API, la richiesta restituisce 403.
Elenca i record di utilizzo
Restituisce una pagina dei record di utilizzo del tuo team, per impostazione predefinita dal più recente. Senza start_time e end_time, i record coprono gli ultimi 30 giorni. Chiamare questo endpoint è gratuito.
I record includono questi task:
- Task API terminati come
SUCCEEDEDoFAILED - Task di ogni membro attuale del team, da qualsiasi delle loro chiavi API
- Task che hai eliminato e task i cui file sono scaduti
I record escludono questi task:
- Task ancora
PENDINGoIN_PROGRESS, e taskCANCELED - Task di persone che hanno lasciato il team
- Task di Creative Lab
- Task eseguiti dagli agenti IA di Meshy
- Lavoro svolto nell'app web di Meshy
Un task appare nei record solo dopo che è terminato, nella finestra del suo created_at. Meshy addebita i crediti quando crea un task, quindi un task ancora in esecuzione è assente dai record. Prima di riconciliare i record con il tuo saldo crediti, ripeti il recupero delle finestre recenti, oppure esporta dopo un breve ritardo.
Se il tuo team ha un periodo di conservazione dei dati, la finestra non inizia prima di quanto consentito da tale periodo.
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": {}
}
]
Parametri
- Name
- page_num
- Type
- integer
- predefinito 1
- Description
La pagina da restituire, da
1a255. Un valore superiore a255restituisce400. Una finestra contiene al massimo 255 pagine, quindi suddividi un'esportazione ampia in finestre più brevi.
- Name
- page_size
- Type
- integer
- predefinito 10
- Description
Numero di record per pagina, da
1a100. Un valore da101a255restituisce 100 record, e un valore superiore a255restituisce400.
- Name
- sort_by
- Type
- string
- predefinito -created_at
- Description
L'ordine di ordinamento.
Valori disponibili:
+created_at: dal più vecchio-created_at: dal più recente
In un URL, scrivi
+come%2B. Altrimenti il+viene interpretato come uno spazio, e la richiesta restituisce400.
- Name
- start_time
- Type
- string
- Description
L'inizio della finestra, come timestamp RFC 3339, per esempio
2026-08-01T00:00:00Z. I record includono i task creati a partire da questo momento incluso. Omettilo per far iniziare la finestra 30 giorni prima diend_time.La finestra può coprire al massimo 366 giorni. Una finestra più lunga restituisce
400, quindi suddividi un'esportazione più lunga in più finestre.
- Name
- end_time
- Type
- string
- Description
La fine della finestra, come timestamp RFC 3339. I record includono i task creati prima di questo momento. Omettilo per far terminare la finestra al momento della tua richiesta.
- Name
- endpoints
- Type
- string
- Description
Un elenco separato da virgole degli endpoint da includere, con gli stessi nomi del campo
endpoint. Omettilo per includere ogni endpoint. Un nome sconosciuto restituisce400.Valori disponibili:
text-to-3d: ogni task di Testo in 3D, preview e refinetext-to-3d-preview: solo i task di previewtext-to-3d-refine: solo i task di refineimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
Lo stato da includere,
SUCCEEDEDoFAILED. Omettilo per includere entrambi. Qualsiasi altro valore restituisce400.
Restituisce
Restituisce un array di record di utilizzo. L'array è vuoto quando nessun record corrisponde.
Modalità di errore
- Name
400 - Bad Request- Description
Un parametro non è valido, e il messaggio di errore indica quale. Correggi il parametro, quindi invia nuovamente la richiesta.
- Name
401 - Unauthorized- Description
La chiave API è mancante o non valida. Controlla l'header
Authorization.
- Name
403 - Forbidden- Description
L'account della chiave API non è un membro attivo di un team Studio o Enterprise. Il messaggio è
This endpoint is available on Studio and Enterprise plans. Usa una chiave API di un membro di un team Studio o Enterprise.
- Name
429 - Too Many Requests- Description
Hai inviato troppe richieste. Attendi il numero di secondi indicato in
Retry-After, quindi riprova.
L'oggetto record di utilizzo
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 del task, lo stesso ID restituito dall'endpoint che lo ha creato. Per ottenere il task stesso, con i suoi URL di output, invia l'ID alla route get di quell'endpoint, per esempio
GET /openapi/v1/image-to-3d/{task_id}per un recordimage-to-3d.
- Name
- endpoint
- Type
- string
- Description
L'endpoint su cui è stato eseguito il task, per esempio
image-to-3dorig. Un task di Testo in 3D mostra il suo stage,text-to-3d-previewotext-to-3d-refine.I record più vecchi possono avere nomi di endpoint dismessi, che il filtro
endpointsnon accetta.
- Name
- status
- Type
- string
- Description
Lo stato finale del task,
SUCCEEDEDoFAILED.
- Name
- created_at
- Type
- timestamp
- Description
Momento in cui il task è stato creato, in millisecondi Unix.
- Name
- finished_at
- Type
- timestamp
- Description
Momento in cui il task è terminato, in millisecondi Unix.
nullse il task non ha un momento di fine.
- Name
- consumed_credits
- Type
- integer
- Description
Numero di crediti usati dal task, dopo i rimborsi.
0per un task fallito, perché Meshy lo rimborsa, e per un task gratuito come Analizza stampabilità.
- Name
- api_key_name
- Type
- string
- Description
Il nome della chiave API con cui è stato eseguito il task. Per un task eseguito con un login da app, è il nome dell'app, per esempio
Meshy CLI.È una stringa vuota in alcuni casi, per esempio:
- Al task non è mai stato addebitato nulla, come un task Analizza stampabilità, che è gratuito.
- La chiave API è stata eliminata.
- La chiave API è stata creata negli ultimi minuti.
- Name
- api_key_suffix
- Type
- string
- Description
Gli ultimi quattro caratteri di quella chiave API, per distinguere chiavi con lo stesso nome. Una stringa vuota quando
api_key_nameè vuoto, e per i login da app come Meshy CLI.
- Name
- metadata
- Type
- object
- Description
I tag inviati nell'header
X-Meshy-Metadataquando il task è stato creato.{}se nessuno. Vedi Metadata.