API Użycia

API Użycia zwraca historyczne zadania API Twojego zespołu wraz z kredytami zużytymi przez każde z nich. Filtruj według przedziału czasowego, punktu końcowego lub statusu i przeglądaj wyniki stronami, aby eksportować je masowo.

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

GET/openapi/v1/usage/tasks

Lista rekordów użycia

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

Parametry

  • Name
    page_num
    Type
    integer
    domyślne 1
    Description

    Numer strony na potrzeby 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 następuje sortowanie.

    Dostępne wartości:

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

    Początek przedziału created_at, jako znacznik czasu RFC 3339 (np. 2026-08-01T00:00:00Z). Domyślnie ustawiany na 30 dni przed end_time. Przedział może obejmować maksymalnie 1 rok — w przypadku większych eksportów przeglądaj kolejne przedziały po kolei.

  • Name
    end_time
    Type
    string
    Description

    Koniec przedziału created_at, jako znacznik czasu RFC 3339. Domyślnie ustawiany na 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, które 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 wartością zbiorczą obejmującą zarówno fazę wstępną (preview), jak i fazę dopracowania (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 wciąż wykonywane w chwili eksportu nie znajdzie się jeszcze w wynikach danego przedziału — ponownie pobierz ostatnie przedziały (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 okresu 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"
  }
]

Obiekt rekordu użycia

  • Name
    task_id
    Type
    string
    Description

    ID zadania, za które ten rekord nalicza opłaty — 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 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 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 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

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

  • Name
    api_key_suffix
    Type
    string
    Description

    Ostatnie cztery znaki tego klucza API, pozwalające odróżnić klucze 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"
}