Usage API

Usage API zwraca historyczne zadania API Twojego zespołu wraz z liczbą kredytów zużytych przez każde z nich. Filtruj według okna czasowego, punktu końcowego lub statusu i przechodź przez wyniki stronami, aby eksportować je zbiorczo.

Dostępność. Klucz API musi należeć do zespołu na planie Studio lub Enterprise; klucze na innych planach lub bez przypisanego zespołu otrzymają odpowiedź 403.

GET/openapi/v1/usage/tasks

List Usage Records

Zwraca jedną stronę zadań API zespołu, od najnowszych. Bez podania wyraźnego zakresu czasu odpowiedź obejmuje ostatnie 30 dni.

Parametry

  • Name
    page_num
    Type
    integer
    domyślne 1
    Description

    Numer strony do stronicowania.

  • Name
    page_size
    Type
    integer
    domyślne 10
    Description

    Limit rozmiaru strony. Maksymalna dozwolona wartość to 100 elementów.

  • Name
    sort_by
    Type
    string
    domyślne -created_at
    Description

    Pole, według którego ma nastąpić sortowanie.

    Dostępne wartości:

    • +created_at: Sortuj według czasu utworzenia rosnąco.
    • -created_at: Sortuj według czasu utworzenia malejąco.
  • Name
    start_time
    Type
    string
    Description

    Początek okna created_at, jako znacznik czasu RFC 3339 (np. 2026-08-01T00:00:00Z). Domyślnie 30 dni przed end_time. Okno może obejmować maksymalnie 1 rok — w przypadku większych eksportów przechodź przez kolejne okna.

  • Name
    end_time
    Type
    string
    Description

    Koniec okna created_at, jako znacznik czasu RFC 3339. Domyślnie bieżący czas.

  • Name
    endpoints
    Type
    string
    Description

    Lista nazw punktów końcowych oddzielonych przecinkami, które mają zostać uwzględnione. Akceptuje te same wartości, jakie przenosi pole odpowiedzi endpoint — 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 — gdzie text-to-3d jest kategorią nadrzędną obejmującą zarówno fazę preview, jak i refine. Pomiń, aby uwzględnić wszystkie punkty końcowe.

  • Name
    status
    Type
    string
    Description

    Filtruj według końcowego statusu zadania: SUCCEEDED lub FAILED. Pomiń, aby uwzględnić oba.

Zwraca

Zwraca stronicowaną listę obiektów rekordu użycia.

Rekordy obejmują zadania, które osiągnęły status końcowy. Kredyty są pobierane w momencie utworzenia zadania, więc zadanie nadal wykonywane w momencie eksportu nie znajdzie się jeszcze w wynikach danego okna — ponów pobranie ostatnich okien (lub eksportuj z niewielkim opóźnieniem), jeśli sumy muszą dokładnie odpowiadać saldu kredytów.

Zespoły z niestandardową polityką przechowywania danych otrzymują rekordy w ramach skonfigurowanego przez siebie okna przechowywania.

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

The Usage Record Object

  • Name
    task_id
    Type
    string
    Description

    ID zadania, którego dotyczy ten rekord rozliczeniowy — ten sam identyfikator, który zwrócił punkt końcowy tworzący zadanie. Aby pobrać samo zadanie (w tym jego wynikowy model lub adresy URL obrazów, ponownie podpisywane przy każdym odczycie), przekaż go do odpowiedniego punktu końcowego pobierania, np. GET /openapi/v1/{endpoint}/{task_id}.

  • Name
    endpoint
    Type
    string
    Description

    Punkt końcowy, na którym zadanie zostało wykonane, np. image-to-3d lub text-to-3d-refine. Zadania Tekst na 3D raportują swoją fazę (text-to-3d-preview / text-to-3d-refine).

  • Name
    status
    Type
    string
    Description

    Końcowy status zadania: SUCCEEDED lub FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Znacznik czasu utworzenia zadania, w milisekundach.

  • Name
    finished_at
    Type
    timestamp
    Description

    Znacznik czasu zakończenia, w milisekundach. null, jeśli zadanie nie zawiera czasu zakończenia.

  • Name
    consumed_credits
    Type
    integer
    Description

    Kredyty zużyte przez to zadanie. Zwraca 0 dla zadań FAILED (kredyty są zwracane w przypadku niepowodzenia).

  • Name
    api_key_name
    Type
    string
    Description

    Nazwa wyświetlana klucza API, który wykonał zadanie. Pozostaje wypełniona nawet dla unieważnionych kluczy, dzięki czemu historyczne wydatki pozostają możliwe do przypisania po rotacji klucza.

  • Name
    api_key_suffix
    Type
    string
    Description

    Ostatnie cztery znaki tego klucza API, umożliwiające odróżnienie kluczy o tej samej nazwie.

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