API Użycia

Wyświetl listę zakończonych zadań API Twojego zespołu oraz liczbę kredytów zużytych przez każde z nich, na potrzeby eksportów rozliczeniowych 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. Z każdym innym kluczem API żądanie zwraca 403.

GET/openapi/v1/usage/tasks

Lista 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 ich 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 oknie czasowym jego created_at. Meshy nalicza kredyty w momencie utworzenia zadania, więc zadanie, które wciąż się wykonuje, nie pojawi się w rekordach. Zanim porównasz rekordy z saldem kredytów, pobierz ponownie ostatnie okna czasowe lub wykonaj eksport z niewielkim opóźnieniem.

Jeśli Twój zespół ma ustalony okres przechowywania danych, okno czasowe 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. Jedno okno czasowe zawiera maksymalnie 255 stron, więc duży eksport podziel na krótsze okna.
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 okna czasowego, jako znacznik czasu RFC 3339, na przykład 2026-08-01T00:00:00Z. Rekordy obejmują zadania utworzone w tym momencie lub później. Pomiń ten parametr, aby okno rozpoczynało się 30 dni przed end_time.
Okno czasowe może obejmować maksymalnie 366 dni. Dłuższe okno zwraca 400, więc dłuższy eksport podziel na kilka okien.
Name
end_time
Type
string
Description
Koniec okna czasowego, jako znacznik czasu RFC 3339. Rekordy obejmują zadania utworzone przed tym momentem. Pomiń ten parametr, aby okno kończyło się w momencie Twojego żądania.
Name
endpoints
Type
string
Description
Lista punktów końcowych do uwzględnienia, oddzielonych przecinkami, pod tymi samymi nazwami co pole endpoint. Pomiń ten parametr, aby uwzględnić każdy punkt końcowy. Nieznana nazwa zwraca 400.
Dostępne wartości:
- text-to-3d: każde zadanie Tekst na 3D, preview 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
Name
status
Type
string
Description
Status do uwzględnienia, SUCCEEDED lub FAILED. Pomiń ten parametr, aby uwzględnić oba. Każda inna wartość zwraca 400.

Zwraca

Zwraca tablicę rekordów użycia. Tablica jest pusta, gdy żaden rekord nie pasuje.

Tryby niepowodzenia

Name
400 - Bad Request
Description
Parametr jest nieprawidłowy, a komunikat o błędzie wskazuje który. Popraw parametr, a następnie wyślij żądanie ponownie.
Name
401 - Unauthorized
Description
Klucz API jest nieobecny lub nieprawidłowy. Sprawdź nagłówek Authorization.
Name
403 - Forbidden
Description
Konto przypisane do klucza API nie jest aktywnym członkiem zespołu Studio lub Enterprise. Komunikat brzmi 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, 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 zwrotach. 0 dla zadania zakończonego niepowodzeniem, ponieważ Meshy zwraca za nie kredyty, oraz dla bezpłatnego zadania, takiego jak Analizuj drukowalność.
Name
api_key_name
Type
string
Description
Nazwa klucza API, który wykonał zadanie. Dla zadania wykonanego przy logowaniu z poziomu aplikacji, jest to nazwa aplikacji, na przykład Meshy CLI.
W niektórych przypadkach jest to pusty ciąg znaków, na przykład:
- Za zadanie nigdy nie naliczono opłaty, np. 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 danego klucza API, pozwalające odróżnić klucze o tej samej nazwie. Pusty ciąg znaków zawsze, gdy api_key_name jest puste, oraz dla logowań aplikacji, takich jak Meshy CLI.
Name
metadata
Type
object
Description
Tagi wysłane w nagłówku X-Meshy-Metadata podczas tworzenia zadania. {}, jeśli brak. Zobacz Metadata.