lowpoly zostanie wycofany 30 paź 2026. meshy-7 jako model generowania 3D zostanie wycofany 31 gru 2026; jako model tekstur pozostaje dostępny. Zmień model przed tymi datami, aby uniknąć błędów żądań. Zobacz wszystkie wycofania

Usage API

Wyświetlaj listę ukończonych zadań API Twojego zespołu oraz liczbę kredytów zużytych przez każde z nich, na potrzeby eksportów do rozliczeń i raportów kosztów.

Aby wywołać ten punkt końcowy, użyj klucza API aktywnego członka zespołu Studio lub Enterprise. Może go wywołać dowolny członek, nie tylko właściciele i administratorzy. Przy użyciu dowolnego innego klucza API żądanie zwróci 403.


GET/openapi/v1/usage/tasks

Listowanie rekordów użycia

Zwraca jedną stronę rekordów użycia Twojego zespołu, domyślnie od najnowszych. Bez podania start_time i end_time rekordy obejmują ostatnie 30 dni. Wywołanie tego punktu końcowego jest bezpłatne.

Rekordy obejmują następujące zadania:

  • Zadania API, które zakończyły się statusem SUCCEEDED lub FAILED
  • Zadania każdego obecnego członka zespołu, z dowolnego z jego kluczy API
  • Zadania, które usunąłeś, oraz zadania, których pliki wygasły

Rekordy pomijają następujące zadania:

  • Zadania, które wciąż mają status PENDING lub IN_PROGRESS, oraz zadania CANCELED
  • Zadania osób, które opuściły zespół
  • Zadania Creative Lab
  • Zadania wykonane przez agentów AI Meshy
  • Prace wykonane w aplikacji webowej Meshy

Zadanie pojawia się w rekordach dopiero po zakończeniu, w przedziale czasowym wyznaczonym przez jego created_at. Meshy nalicza kredyty w momencie utworzenia zadania, więc zadanie, które wciąż jest w toku, nie pojawi się w rekordach. Zanim porównasz rekordy z saldem swoich kredytów, pobierz ponownie ostatnie przedziały czasowe lub wykonaj eksport po krótkim opóźnieniu.

Jeśli Twój zespół ma ustalony okres przechowywania danych, przedział czasowy nie może zaczynać się wcześniej, niż pozwala na to ten okres.

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",
    "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": {}
  }
]

Parametry

  • Name
    page_num
    Type
    integer
    domyślne 1
    Description

    Strona do zwrócenia, od 1 do 255. Wartość powyżej 255 zwraca 400. Jeden przedział czasowy pomieści co najwyżej 255 stron, więc podziel duży eksport na krótsze przedziały czasowe.

  • Name
    page_size
    Type
    integer
    domyślne 10
    Description

    Liczba rekordów na stronę, od 1 do 100. Wartość od 101 do 255 zwraca 100 rekordów, a wartość powyżej 255 zwraca 400.

  • Name
    sort_by
    Type
    string
    domyślne -created_at
    Description

    Kolejność sortowania.

    Dostępne wartości:

    • +created_at: od najstarszych
    • -created_at: od najnowszych

    W adresie URL zapisz + jako %2B. W przeciwnym razie + zostanie odczytany jako spacja, a żądanie zwróci 400.

  • Name
    start_time
    Type
    string
    Description

    Początek przedziału czasowego, jako znacznik czasu w formacie RFC 3339, na przykład 2026-08-01T00:00:00Z. Rekordy obejmują zadania utworzone w tym momencie lub później. Pomiń ten parametr, aby przedział czasowy zaczynał się 30 dni przed end_time.

    Przedział czasowy może obejmować co najwyżej 366 dni. Dłuższy przedział zwraca 400, więc podziel dłuższy eksport na kilka przedziałów czasowych.

  • Name
    end_time
    Type
    string
    Description

    Koniec przedziału czasowego, jako znacznik czasu w formacie RFC 3339. Rekordy obejmują zadania utworzone przed tym momentem. Pomiń ten parametr, aby przedział czasowy kończył się w momencie wysłania żądania.

  • Name
    endpoints
    Type
    string
    Description

    Lista punktów końcowych do uwzględnienia, rozdzielonych przecinkami, zapisanych pod tymi samymi nazwami co pole endpoint. Pomiń ten parametr, aby uwzględnić wszystkie punkty końcowe. Nieznana nazwa zwraca 400.

    Dostępne wartości:

    • text-to-3d: każde zadanie Tekst na 3D, zarówno preview, jak i refine
    • text-to-3d-preview: tylko zadania preview
    • text-to-3d-refine: tylko zadania 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
    • relief
  • Name
    status
    Type
    string
    Description

    Status do uwzględnienia, SUCCEEDED lub FAILED. Pomiń ten parametr, aby uwzględnić oba. Jakakolwiek inna wartość zwraca 400.

Zwracane dane

Zwraca tablicę rekordów użycia. Tablica jest pusta, gdy żaden rekord nie spełnia kryteriów.

Przypadki niepowodzenia

  • Name
    400 - Bad Request
    Description

    Jeden z parametrów jest nieprawidłowy, a komunikat o błędzie wskazuje który. Popraw parametr i wyślij żądanie ponownie.

  • Name
    401 - Unauthorized
    Description

    Klucz API jest brakujący lub nieprawidłowy. Sprawdź nagłówek Authorization.

  • Name
    403 - Forbidden
    Description

    Konto klucza API nie jest aktywnym członkiem zespołu Studio lub Enterprise. Komunikat to This endpoint is available on Studio and Enterprise plans. Użyj klucza API członka zespołu Studio lub Enterprise.

  • Name
    429 - Too Many Requests
    Description

    Wysłano zbyt wiele żądań. Odczekaj liczbę sekund podaną w Retry-After, a następnie spróbuj ponownie.


Obiekt rekordu użycia

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

    Identyfikator zadania, ten sam identyfikator, który zwrócił tworzący je punkt końcowy. Aby pobrać samo zadanie wraz z adresami URL wyników, wyślij ten identyfikator do trasy pobierania tego punktu końcowego, na przykład GET /openapi/v1/image-to-3d/{task_id} dla rekordu image-to-3d.

  • Name
    endpoint
    Type
    string
    Description

    Punkt końcowy, na którym wykonano zadanie, na przykład image-to-3d lub rig. Zadanie Tekst na 3D pokazuje swój etap, text-to-3d-preview lub text-to-3d-refine.

    Starsze rekordy mogą zawierać nazwy wycofanych punktów końcowych, których filtr endpoints nie akceptuje.

  • Name
    status
    Type
    string
    Description

    Ostateczny status zadania, SUCCEEDED lub FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Czas utworzenia zadania, w milisekundach Unix.

  • Name
    finished_at
    Type
    timestamp
    Description

    Czas zakończenia zadania, w milisekundach Unix. null, jeśli zadanie nie ma czasu zakończenia.

  • Name
    consumed_credits
    Type
    integer
    Description

    Liczba kredytów zużytych przez zadanie, po uwzględnieniu zwrotów. 0 dla zadania zakończonego niepowodzeniem, ponieważ Meshy zwraca za nie kredyty, oraz dla zadania bezpłatnego, takiego jak Analizuj drukowalność.

  • Name
    api_key_name
    Type
    string
    Description

    Nazwa klucza API, który wykonał zadanie. Dla zadania wykonanego przy użyciu logowania aplikacją jest to nazwa aplikacji, na przykład Meshy CLI.

    Jest to pusty ciąg znaków w niektórych przypadkach, na przykład:

    • Zadanie nigdy nie zostało obciążone kredytami, tak jak zadanie Analizuj drukowalność, które jest bezpłatne.
    • Klucz API został usunięty.
    • Klucz API został utworzony w ciągu ostatnich kilku minut.
  • Name
    api_key_suffix
    Type
    string
    Description

    Cztery ostatnie znaki tego klucza API, aby odróżnić klucze o tej samej nazwie. Pusty ciąg znaków zawsze, gdy api_key_name jest pusty, oraz dla logowań aplikacją, takich jak Meshy CLI.

  • Name
    metadata
    Type
    object
    Description

    Tagi wysłane w nagłówku X-Meshy-Metadata w momencie utworzenia zadania. {}, jeśli ich brak. Zobacz Metadata.