lowpoly verrà ritirato il 30 ott 2026. meshy-7 come modello di generazione 3D verrà ritirato il 31 dic 2026; come modello di texture resta disponibile. Cambia modello prima di queste date per evitare errori nelle richieste. Vedi tutte le deprecazioni

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.


GET/openapi/v1/usage/tasks

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 SUCCEEDED o FAILED
  • 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 PENDING o IN_PROGRESS, e task CANCELED
  • 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

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

Parametri

  • Name
    page_num
    Type
    integer
    predefinito 1
    Description

    La pagina da restituire, da 1 a 255. Un valore superiore a 255 restituisce 400. 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 1 a 100. Un valore da 101 a 255 restituisce 100 record, e un valore superiore a 255 restituisce 400.

  • 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 restituisce 400.

  • 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 di end_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 restituisce 400.

    Valori disponibili:

    • text-to-3d: ogni task di Testo in 3D, preview e refine
    • text-to-3d-preview: solo i task di preview
    • text-to-3d-refine: solo i task di 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
    • relief
  • Name
    status
    Type
    string
    Description

    Lo stato da includere, SUCCEEDED o FAILED. Omettilo per includere entrambi. Qualsiasi altro valore restituisce 400.

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 record image-to-3d.

  • Name
    endpoint
    Type
    string
    Description

    L'endpoint su cui è stato eseguito il task, per esempio image-to-3d o rig. Un task di Testo in 3D mostra il suo stage, text-to-3d-preview o text-to-3d-refine.

    I record più vecchi possono avere nomi di endpoint dismessi, che il filtro endpoints non accetta.

  • Name
    status
    Type
    string
    Description

    Lo stato finale del task, SUCCEEDED o FAILED.

  • 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. null se il task non ha un momento di fine.

  • Name
    consumed_credits
    Type
    integer
    Description

    Numero di crediti usati dal task, dopo i rimborsi. 0 per 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-Metadata quando il task è stato creato. {} se nessuno. Vedi Metadata.