Usage API

Usage API zwraca historyczne zadania API Twojego zespołu wraz z kredytami zużytymi przez każde z nich. Filtruj według przedziału czasu, punktu końcowego lub statusu i przechodź przez wyniki stronami, aby eksportować je masowo.

Dostępność. Klucz API musi należeć do zespołu na planie Studio lub Enterprise; klucze na jakimkolwiek innym planie 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 wyraźnie podanego przedziału czasu odpowiedź obejmuje ostatnie 30 dni.

Parametry

  • Name
    page_num
    Type
    integer
    domyślne 1
    Description

    Numer strony dla stronicowania.

  • Name
    page_size
    Type
    integer
    domyślne 10
    Description

    Limit rozmiaru strony. Maksymalna dopuszczalna 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 w porządku wzrastającym.
    • -created_at: Sortuj według czasu utworzenia w porządku malejącym.
  • Name
    start_time
    Type
    string
    Description

    Początek przedziału created_at, jako znacznik czasu w formacie RFC 3339 (np. 2026-08-01T00:00:00Z). Wartość domyślna to 30 dni przed end_time. Przedział może obejmować maksymalnie 1 rok — w przypadku większych eksportów przechodź przez kolejne przedziały stronami.

  • Name
    end_time
    Type
    string
    Description

    Koniec przedziału created_at, jako znacznik czasu w formacie RFC 3339. Wartość domyślna to aktualny czas.

  • Name
    endpoints
    Type
    string
    Description

    Lista nazw punktów końcowych rozdzielonych przecinkami, które mają zostać uwzględnione. Przyjmuje te same wartości, które niesie pole endpoint w odpowiedzi — 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, print-split — 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ć obie wartości.

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 wciąż wykonywane w chwili eksportu nie znajdzie się jeszcze w wynikach danego przedziału — ponownie pobierz najnowsze przedziały (lub eksportuj z niewielkim opóźnieniem), jeśli suma musi dokładnie odpowiadać saldu kredytów.

Zespoły z niestandardową polityką przechowywania danych otrzymują rekordy w skonfigurowanym oknie 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 rozliczanego przez ten rekord — ten sam identyfikator, który zwrócił punkt końcowy tworzący zadanie. Aby pobrać samo zadanie (w tym adresy URL wynikowego modelu lub obrazu, ponownie podpisywane przy każdym odczycie), przekaż go do odpowiedniego punktu końcowego do pobierania, np. GET /openapi/v1/{endpoint}/{task_id}.

  • Name
    endpoint
    Type
    string
    Description

    Punkt końcowy, na którym uruchomiono zadanie, np. image-to-3d lub text-to-3d-refine. Zadania Tekst na 3D zgłaszają 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 posiada 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

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

  • Name
    api_key_suffix
    Type
    string
    Description

    Ostatnie cztery znaki tego klucza API, umożliwiające rozróż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"
}