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.
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
SUCCEEDEDoderFAILEDabgeschlossen 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
PENDINGoderIN_PROGRESSsind, sowieCANCELED-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
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
1bis255. Ein Wert über255liefert400. 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
1bis100. Ein Wert von101bis255liefert 100 Datensätze, und ein Wert über255liefert400.
- 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 liefert400.
- 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 vorend_timebeginnt.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 liefert400.Verfügbare Werte:
text-to-3d: jeder Text zu 3D-Task, preview und refinetext-to-3d-preview: nur preview-Taskstext-to-3d-refine: nur refine-Tasksimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
Der einzuschließende Status,
SUCCEEDEDoderFAILED. Lasse es weg, um beide einzuschließen. Jeder andere Wert liefert400.
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-Afterangegebene 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 einenimage-to-3d-Datensatz.
- Name
- endpoint
- Type
- string
- Description
Der Endpunkt, auf dem der Task ausgeführt wurde, zum Beispiel
image-to-3doderrig. Ein Text zu 3D-Task zeigt seine Stufe,text-to-3d-previewodertext-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,
SUCCEEDEDoderFAILED.
- 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.
0fü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_nameleer 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.