lowpoly wordt op 30 okt 2026 uitgefaseerd. meshy-7 als 3D-generatiemodel wordt op 31 dec 2026 uitgefaseerd; als textuurmodel blijft het beschikbaar. Stap vóór deze datums over op een ander model om fouten bij verzoeken te voorkomen. Alle afschaffingen bekijken

Usage API

Geef de voltooide API-taken van je team weer en de credits die elke taak heeft gebruikt, voor factureringsexports en kostenrapporten.

Gebruik voor het aanroepen van deze endpoint een API-sleutel van een actief lid van een Studio- of Enterprise-team. Elk lid kan dit aanroepen, niet alleen eigenaars en beheerders. Met elke andere API-sleutel geeft het verzoek 403 terug.


GET/openapi/v1/usage/tasks

Gebruiksrecords weergeven

Geeft één pagina terug met de gebruiksrecords van je team, standaard nieuwste eerst. Zonder start_time en end_time bestrijken de records de laatste 30 dagen. Het aanroepen van deze endpoint is gratis.

De records bevatten deze taken:

  • API-taken die zijn afgerond met status SUCCEEDED of FAILED
  • Taken van elk huidig lid van het team, vanaf elk van hun API-sleutels
  • Taken die je hebt verwijderd, en taken waarvan de bestanden zijn verlopen

De records bevatten deze taken niet:

  • Taken die nog PENDING of IN_PROGRESS zijn, en CANCELED-taken
  • Taken van mensen die het team hebben verlaten
  • Creative Lab-taken
  • Taken die door Meshy's AI-agents zijn uitgevoerd
  • Werk gedaan in de Meshy web-app

Een taak verschijnt pas in de records nadat deze is voltooid, binnen het venster van created_at. Meshy brengt credits in rekening op het moment dat een taak wordt aangemaakt, dus een taak die nog loopt, ontbreekt in de records. Voordat je de records afstemt met je credit-saldo, haal recente vensters opnieuw op, of exporteer na een korte vertraging.

Als je team een gegevensbewaartermijn heeft, begint het venster niet eerder dan die termijn toestaat.

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

Parameters

  • Name
    page_num
    Type
    integer
    standaard 1
    Description

    De te retourneren pagina, van 1 tot 255. Een waarde boven 255 geeft 400 terug. Eén venster bevat maximaal 255 pagina's, dus splits een grote export op in kortere vensters.

  • Name
    page_size
    Type
    integer
    standaard 10
    Description

    Aantal records per pagina, van 1 tot 100. Een waarde van 101 tot 255 geeft 100 records terug, en een waarde boven 255 geeft 400 terug.

  • Name
    sort_by
    Type
    string
    standaard -created_at
    Description

    De sorteervolgorde.

    Beschikbare waarden:

    • +created_at: oudste eerst
    • -created_at: nieuwste eerst

    Schrijf in een URL + als %2B. Anders wordt de + gelezen als een spatie, en geeft het verzoek 400 terug.

  • Name
    start_time
    Type
    string
    Description

    Het begin van het venster, als een RFC 3339-tijdstempel, bijvoorbeeld 2026-08-01T00:00:00Z. De records bevatten taken die zijn aangemaakt op of na dit tijdstip. Laat dit weg om het venster 30 dagen vóór end_time te laten beginnen.

    Het venster kan maximaal 366 dagen beslaan. Een langer venster geeft 400 terug, dus splits een langere export op in meerdere vensters.

  • Name
    end_time
    Type
    string
    Description

    Het einde van het venster, als een RFC 3339-tijdstempel. De records bevatten taken die zijn aangemaakt vóór dit tijdstip. Laat dit weg om het venster te laten eindigen op het moment van je verzoek.

  • Name
    endpoints
    Type
    string
    Description

    Een door komma's gescheiden lijst van de op te nemen endpoints, met dezelfde namen als het veld endpoint. Laat dit weg om elke endpoint op te nemen. Een onbekende naam geeft 400 terug.

    Beschikbare waarden:

    • text-to-3d: elke Tekst naar 3D-taak, preview en refine
    • text-to-3d-preview: alleen preview-taken
    • text-to-3d-refine: alleen refine-taken
    • 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

    De op te nemen status, SUCCEEDED of FAILED. Laat dit weg om beide op te nemen. Elke andere waarde geeft 400 terug.

Retourneert

Geeft een array van gebruiksrecords terug. De array is leeg wanneer er geen records overeenkomen.

Foutmodi

  • Name
    400 - Bad Request
    Description

    Een parameter is ongeldig, en het foutbericht geeft aan welke. Corrigeer de parameter en stuur het verzoek opnieuw.

  • Name
    401 - Unauthorized
    Description

    De API-sleutel ontbreekt of is ongeldig. Controleer de Authorization-header.

  • Name
    403 - Forbidden
    Description

    Het account van de API-sleutel is geen actief lid van een Studio- of Enterprise-team. Het bericht is This endpoint is available on Studio and Enterprise plans. Gebruik een API-sleutel van een lid van een Studio- of Enterprise-team.

  • Name
    429 - Too Many Requests
    Description

    Je hebt te veel verzoeken verstuurd. Wacht het aantal seconden in Retry-After, en probeer het dan opnieuw.


Het gebruiksrecord-object

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

    De taak-ID, dezelfde ID die de aanmakende endpoint heeft teruggegeven. Om de taak zelf op te halen, met de output-URL's, stuur de ID naar de get-route van die endpoint, bijvoorbeeld GET /openapi/v1/image-to-3d/{task_id} voor een image-to-3d-record.

  • Name
    endpoint
    Type
    string
    Description

    De endpoint waarop de taak is uitgevoerd, bijvoorbeeld image-to-3d of rig. Een Tekst naar 3D-taak toont zijn fase, text-to-3d-preview of text-to-3d-refine.

    Oudere records kunnen namen van uitgefaseerde endpoints bevatten, die het endpoints-filter niet accepteert.

  • Name
    status
    Type
    string
    Description

    De uiteindelijke status van de taak, SUCCEEDED of FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Tijdstip waarop de taak is aangemaakt, in Unix-milliseconden.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tijdstip waarop de taak is voltooid, in Unix-milliseconden. null als de taak geen voltooiingstijd heeft.

  • Name
    consumed_credits
    Type
    integer
    Description

    Aantal credits dat de taak heeft gebruikt, na terugbetalingen. 0 voor een mislukte taak, omdat Meshy deze terugbetaalt, en voor een gratis taak zoals Printbaarheid analyseren.

  • Name
    api_key_name
    Type
    string
    Description

    De naam van de API-sleutel waarmee de taak is uitgevoerd. Voor een taak uitgevoerd met een app-login is dit de naam van de app, bijvoorbeeld Meshy CLI.

    Het is in sommige gevallen een lege string, bijvoorbeeld:

    • Er is nooit iets in rekening gebracht voor de taak, zoals een Printbaarheid analyseren-taak, die gratis is.
    • De API-sleutel is verwijderd.
    • De API-sleutel is in de afgelopen paar minuten aangemaakt.
  • Name
    api_key_suffix
    Type
    string
    Description

    De laatste vier tekens van die API-sleutel, om sleutels met dezelfde naam van elkaar te onderscheiden. Een lege string wanneer api_key_name leeg is, en voor app-logins zoals de Meshy CLI.

  • Name
    metadata
    Type
    object
    Description

    De tags die zijn verzonden in de X-Meshy-Metadata-header toen de taak werd aangemaakt. {} als er geen zijn. Zie Metadata.