lowpoly wird am 30.10.2026 abgeschaltet. meshy-7 wird als 3D-Generierungsmodell am 31.12.2026 abgeschaltet; als Texturmodell bleibt es verfügbar. Wechseln Sie vor diesen Terminen das Modell, um Fehler bei Anfragen zu vermeiden. Alle Abkündigungen ansehen

Usage API

Listet die abgeschlossenen API-Tasks deines Teams und die dabei verbrauchten Credits auf – für Abrechnungsexporte und Kostenberichte.

Um diesen Endpunkt aufzurufen, verwende einen API-Schlüssel eines aktiven Mitglieds eines Studio- oder Enterprise-Teams. Jedes Mitglied kann ihn aufrufen, nicht nur Inhaber und Admins. Mit jedem anderen API-Schlüssel liefert die Anfrage 403.


GET/openapi/v1/usage/tasks

Nutzungsdatensätze auflisten

Gibt eine Seite der Nutzungsdatensätze deines Teams zurück, standardmäßig die neuesten zuerst. Ohne start_time und end_time umfassen die Datensätze die letzten 30 Tage. Der Aufruf dieses Endpunkts ist kostenlos.

Die Datensätze enthalten folgende Tasks:

  • API-Tasks, die mit SUCCEEDED oder FAILED abgeschlossen wurden
  • Tasks jedes aktuellen Mitglieds des Teams, von jedem ihrer API-Schlüssel
  • Von dir gelöschte Tasks sowie Tasks, deren Dateien abgelaufen sind

Die Datensätze lassen folgende Tasks aus:

  • Tasks, die noch PENDING oder IN_PROGRESS sind, sowie CANCELED-Tasks
  • Tasks von Personen, die das Team verlassen haben
  • Creative Lab-Tasks
  • Tasks, die von Meshys KI-Agenten ausgeführt wurden
  • Arbeiten, die in der Meshy Web-App ausgeführt wurden

Ein Task erscheint erst nach seinem Abschluss in den Datensätzen, im Zeitfenster seines created_at-Werts. Meshy belastet Credits, wenn es einen Task erstellt, daher fehlt ein noch laufender Task in den Datensätzen. Bevor du die Datensätze mit deinem Credit-Guthaben abgleichst, rufe aktuelle Zeitfenster erneut ab oder exportiere nach einer kurzen Verzögerung.

Wenn dein Team eine Datenaufbewahrungsfrist hat, beginnt das Zeitfenster frühestens so, wie es diese Frist erlaubt.

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

Parameter

  • Name
    page_num
    Type
    integer
    Standard 1
    Description

    Die zurückzugebende Seite, von 1 bis 255. Ein Wert über 255 liefert 400. Ein Zeitfenster enthält maximal 255 Seiten, teile daher einen großen Export in kürzere Zeitfenster auf.

  • Name
    page_size
    Type
    integer
    Standard 10
    Description

    Anzahl der Datensätze pro Seite, von 1 bis 100. Ein Wert von 101 bis 255 liefert 100 Datensätze, und ein Wert über 255 liefert 400.

  • Name
    sort_by
    Type
    string
    Standard -created_at
    Description

    Die Sortierreihenfolge.

    Verfügbare Werte:

    • +created_at: älteste zuerst
    • -created_at: neueste zuerst

    Schreibe in einer URL + als %2B. Andernfalls wird das + als Leerzeichen gelesen, und die Anfrage liefert 400.

  • Name
    start_time
    Type
    string
    Description

    Der Anfang des Zeitfensters, als RFC 3339-Zeitstempel, zum Beispiel 2026-08-01T00:00:00Z. Die Datensätze enthalten Tasks, die zu diesem Zeitpunkt oder danach erstellt wurden. Lasse es weg, damit das Zeitfenster 30 Tage vor end_time beginnt.

    Das Zeitfenster kann höchstens 366 Tage umfassen. Ein längeres Zeitfenster liefert 400, teile einen längeren Export daher in mehrere Zeitfenster auf.

  • Name
    end_time
    Type
    string
    Description

    Das Ende des Zeitfensters, als RFC 3339-Zeitstempel. Die Datensätze enthalten Tasks, die vor diesem Zeitpunkt erstellt wurden. Lasse es weg, damit das Zeitfenster zum Zeitpunkt deiner Anfrage endet.

  • Name
    endpoints
    Type
    string
    Description

    Eine durch Kommas getrennte Liste der einzuschließenden Endpunkte, mit denselben Namen wie das Feld endpoint. Lasse es weg, um jeden Endpunkt einzuschließen. Ein unbekannter Name liefert 400.

    Verfügbare Werte:

    • text-to-3d: jeder Text zu 3D-Task, preview und refine
    • text-to-3d-preview: nur preview-Tasks
    • text-to-3d-refine: nur refine-Tasks
    • 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

    Der einzuschließende Status, SUCCEEDED oder FAILED. Lasse es weg, um beide einzuschließen. Jeder andere Wert liefert 400.

Rückgabewerte

Gibt ein Array von Nutzungsdatensätzen zurück. Das Array ist leer, wenn keine Datensätze übereinstimmen.

Fehlerfälle

  • Name
    400 - Bad Request
    Description

    Ein Parameter ist ungültig, und die Fehlermeldung gibt an, welcher. Korrigiere den Parameter und sende die Anfrage erneut.

  • Name
    401 - Unauthorized
    Description

    Der API-Schlüssel fehlt oder ist ungültig. Überprüfe den Authorization-Header.

  • Name
    403 - Forbidden
    Description

    Das Konto des API-Schlüssels ist kein aktives Mitglied eines Studio- oder Enterprise-Teams. Die Meldung lautet This endpoint is available on Studio and Enterprise plans. Verwende einen API-Schlüssel eines Studio- oder Enterprise-Teammitglieds.

  • Name
    429 - Too Many Requests
    Description

    Du hast zu viele Anfragen gesendet. Warte die in Retry-After angegebene Anzahl Sekunden und versuche es erneut.


Das Nutzungsdatensatz-Objekt

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

    Die Task-ID, dieselbe ID, die der erstellende Endpunkt zurückgegeben hat. Um den Task selbst mit seinen Ausgabe-URLs zu erhalten, sende die ID an die Get-Route dieses Endpunkts, zum Beispiel GET /openapi/v1/image-to-3d/{task_id} für einen image-to-3d-Datensatz.

  • Name
    endpoint
    Type
    string
    Description

    Der Endpunkt, auf dem der Task ausgeführt wurde, zum Beispiel image-to-3d oder rig. Ein Text zu 3D-Task zeigt seine Stufe, text-to-3d-preview oder text-to-3d-refine.

    Ältere Datensätze können Namen eingestellter Endpunkte enthalten, die der endpoints-Filter nicht akzeptiert.

  • Name
    status
    Type
    string
    Description

    Der endgültige Status des Tasks, SUCCEEDED oder FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitpunkt, zu dem der Task erstellt wurde, in Unix-Millisekunden.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitpunkt, zu dem der Task abgeschlossen wurde, in Unix-Millisekunden. null, wenn der Task keinen Abschlusszeitpunkt hat.

  • Name
    consumed_credits
    Type
    integer
    Description

    Anzahl der vom Task verbrauchten Credits, nach Erstattungen. 0 für einen fehlgeschlagenen Task, da Meshy ihn erstattet, sowie für einen kostenlosen Task wie Druckbarkeit analysieren.

  • Name
    api_key_name
    Type
    string
    Description

    Der Name des API-Schlüssels, mit dem der Task ausgeführt wurde. Bei einem Task, der mit einem App-Login ausgeführt wurde, ist es der Name der App, zum Beispiel Meshy CLI.

    In manchen Fällen ist es ein leerer String, zum Beispiel:

    • Dem Task wurden nie Credits berechnet, etwa bei einem Druckbarkeit analysieren-Task, der kostenlos ist.
    • Der API-Schlüssel wurde gelöscht.
    • Der API-Schlüssel wurde in den letzten paar Minuten erstellt.
  • Name
    api_key_suffix
    Type
    string
    Description

    Die letzten vier Zeichen dieses API-Schlüssels, um Schlüssel mit demselben Namen zu unterscheiden. Ein leerer String, wann immer api_key_name leer ist, sowie bei App-Logins wie der Meshy CLI.

  • Name
    metadata
    Type
    object
    Description

    Die im X-Meshy-Metadata-Header gesendeten Tags, als der Task erstellt wurde. {}, falls keine vorhanden sind. Siehe Metadata.