Nutzungs-API

Die Nutzungs-API liefert die historischen API-Aufgaben Ihres Teams zusammen mit den dabei jeweils verbrauchten Credits. Filtern Sie nach Zeitfenster, Endpunkt oder Status und blättern Sie durch die Ergebnisse, um sie in großen Mengen zu exportieren.

Verfügbarkeit. Der API-Schlüssel muss zu einem Studio- oder Enterprise-Team gehören; Schlüssel eines anderen Plans oder ohne Team erhalten einen 403.

GET/openapi/v1/usage/tasks

Nutzungsdatensätze auflisten

Gibt eine Seite der API-Aufgaben des Teams zurück, neueste zuerst. Ohne explizit angegebenen Zeitraum umfasst die Antwort die letzten 30 Tage.

Parameter

  • Name
    page_num
    Type
    integer
    Standard 1
    Description

    Seitennummer für die Paginierung.

  • Name
    page_size
    Type
    integer
    Standard 10
    Description

    Limit für die Seitengröße. Maximal zulässig sind 100 Einträge.

  • Name
    sort_by
    Type
    string
    Standard -created_at
    Description

    Feld, nach dem sortiert werden soll.

    Verfügbare Werte:

    • +created_at: Sortierung nach Erstellungszeit aufsteigend.
    • -created_at: Sortierung nach Erstellungszeit absteigend.
  • Name
    start_time
    Type
    string
    Description

    Beginn des created_at-Zeitfensters, als RFC-3339-Zeitstempel (z. B. 2026-08-01T00:00:00Z). Standardmäßig 30 Tage vor end_time. Das Zeitfenster darf höchstens 1 Jahr umfassen — für größere Exporte blättern Sie durch aufeinanderfolgende Zeitfenster.

  • Name
    end_time
    Type
    string
    Description

    Ende des created_at-Zeitfensters, als RFC-3339-Zeitstempel. Standardmäßig die aktuelle Zeit.

  • Name
    endpoints
    Type
    string
    Description

    Durch Kommas getrennte Liste der einzuschließenden Endpunktnamen. Akzeptiert dieselben Werte, die das Antwortfeld endpoint enthält — 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 — wobei text-to-3d als Oberbegriff sowohl die Preview- als auch die Refine-Phase abdeckt. Weglassen, um alle Endpunkte einzuschließen.

  • Name
    status
    Type
    string
    Description

    Filtern nach endgültigem Aufgabenstatus: SUCCEEDED oder FAILED. Weglassen, um beide einzuschließen.

Rückgabe

Gibt eine paginierte Liste von Nutzungsdatensatz-Objekten zurück.

Die Datensätze umfassen Aufgaben, die einen endgültigen Status erreicht haben. Credits werden bei der Erstellung einer Aufgabe belastet, sodass eine beim Export noch laufende Aufgabe noch nicht in den Ergebnissen dieses Zeitfensters enthalten ist — rufen Sie aktuelle Zeitfenster erneut ab (oder exportieren Sie mit kurzer Verzögerung), falls Ihre Summen exakt mit Ihrem Credit-Guthaben übereinstimmen müssen.

Teams mit einer benutzerdefinierten Datenaufbewahrungsrichtlinie erhalten Datensätze innerhalb ihres konfigurierten Aufbewahrungsfensters.

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

Das Nutzungsdatensatz-Objekt

  • Name
    task_id
    Type
    string
    Description

    ID der Aufgabe, die dieser Datensatz abrechnet — dieselbe ID, die der erstellende Endpunkt zurückgegeben hat. Um die Aufgabe selbst abzurufen (einschließlich der Ausgabemodell- oder Bild-URLs, die bei jedem Lesevorgang neu signiert werden), übergeben Sie sie an den entsprechenden Abruf-Endpunkt, z. B. GET /openapi/v1/{endpoint}/{task_id}.

  • Name
    endpoint
    Type
    string
    Description

    Der Endpunkt, auf dem die Aufgabe ausgeführt wurde, z. B. image-to-3d oder text-to-3d-refine. Text-zu-3D-Aufgaben melden ihre Phase (text-to-3d-preview / text-to-3d-refine).

  • Name
    status
    Type
    string
    Description

    Endgültiger Aufgabenstatus: SUCCEEDED oder FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitstempel der Erstellung der Aufgabe, in Millisekunden.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitstempel des Abschlusses, in Millisekunden. null, wenn die Aufgabe keine Abschlusszeit enthält.

  • Name
    consumed_credits
    Type
    integer
    Description

    Von dieser Aufgabe verbrauchte Credits. Gibt 0 für FAILED-Aufgaben zurück (Credits werden bei einem Fehlschlag zurückerstattet).

  • Name
    api_key_name
    Type
    string
    Description

    Anzeigename des API-Schlüssels, mit dem die Aufgabe ausgeführt wurde. Bleibt auch für widerrufene Schlüssel erhalten, sodass historische Ausgaben auch nach einer Schlüsselrotation zuordenbar bleiben.

  • Name
    api_key_suffix
    Type
    string
    Description

    Die letzten vier Zeichen dieses API-Schlüssels, um Schlüssel mit demselben Namen voneinander zu unterscheiden.

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