Usage API

L'API Usage restituisce i task API storici del tuo team con i crediti consumati da ciascuno. Filtra per intervallo di tempo, endpoint o stato, e scorri i risultati per esportarli in blocco.

Disponibilità. La chiave API deve appartenere a un team Studio o Enterprise; le chiavi di qualsiasi altro piano, o senza un team, ricevono un 403.

GET/openapi/v1/usage/tasks

Elenca i record di utilizzo

Restituisce una pagina dei task API del team, dal più recente al più vecchio. Senza un intervallo di tempo esplicito, la risposta copre gli ultimi 30 giorni.

Parametri

Name
page_num
Type
integer
predefinito 1
Description
Numero di pagina per la paginazione.
Name
page_size
Type
integer
predefinito 10
Description
Limite di dimensione della pagina. Il massimo consentito è 100 elementi.
Name
sort_by
Type
string
predefinito -created_at
Description
Campo per l'ordinamento.
Valori disponibili:
- +created_at: Ordina per data di creazione in ordine crescente.
- -created_at: Ordina per data di creazione in ordine decrescente.
Name
start_time
Type
string
Description
Inizio della finestra created_at, come timestamp RFC 3339 (es. 2026-08-01T00:00:00Z). Il valore predefinito è 30 giorni prima di end_time. La finestra può coprire al massimo 1 anno — per esportazioni più grandi, scorri finestre consecutive.
Name
end_time
Type
string
Description
Fine della finestra created_at, come timestamp RFC 3339. Il valore predefinito è l'ora corrente.
Name
endpoints
Type
string
Description
Elenco separato da virgole dei nomi di endpoint da includere. Accetta gli stessi valori riportati dal campo di risposta 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 — dove text-to-3d è una categoria che copre sia la fase preview che quella refine. Ometti per includere ogni endpoint.
Name
status
Type
string
Description
Filtra per stato terminale del task: SUCCEEDED o FAILED. Ometti per includere entrambi.

Restituisce

Restituisce un elenco paginato di Oggetti Record di utilizzo.

I record coprono i task che hanno raggiunto uno stato terminale. I crediti vengono addebitati alla creazione di un task, quindi un task ancora in esecuzione al momento dell'esportazione non è ancora presente nei risultati di quella finestra — ripeti l'estrazione delle finestre più recenti (o esporta con un breve ritardo) se i tuoi totali devono corrispondere esattamente al saldo dei tuoi crediti.

I team con una policy di conservazione dati personalizzata ricevono i record entro la loro finestra di conservazione configurata.

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'oggetto Record di utilizzo

Name
task_id
Type
string
Description
ID del task che questo record fattura — lo stesso ID restituito dall'endpoint di creazione. Per recuperare il task stesso (incluso il suo modello di output o gli URL delle immagini, ri-firmati ad ogni lettura), passalo all'endpoint di recupero corrispondente, es. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
L'endpoint su cui è stato eseguito il task, es. image-to-3d o text-to-3d-refine. I task di Testo in 3D riportano la loro fase (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Stato terminale del task: SUCCEEDED o FAILED.
Name
created_at
Type
timestamp
Description
Timestamp di creazione del task, in millisecondi.
Name
finished_at
Type
timestamp
Description
Timestamp di completamento, in millisecondi. null se il task non riporta un orario di completamento.
Name
consumed_credits
Type
integer
Description
Crediti consumati da questo task. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di fallimento).
Name
api_key_name
Type
string
Description
Nome visualizzato della chiave API che ha eseguito il task. Rimane popolato per le chiavi revocate, così la spesa storica resta attribuibile dopo la rotazione delle chiavi.
Name
api_key_suffix
Type
string
Description
Ultimi quattro caratteri di quella chiave API, per distinguere chiavi con lo stesso nome.

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"
}