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.
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
SUCCEEDEDlubFAILED - 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
PENDINGlubIN_PROGRESS, oraz zadaniaCANCELED - 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
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
1do255. Wartość powyżej255zwraca400. 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
1do100. Wartość od101do255zwraca 100 rekordów, a wartość powyżej255zwraca400.
- 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óci400.
- 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 przedend_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 zwraca400.Dostępne wartości:
text-to-3d: każde zadanie Tekst na 3D, zarówno preview, jak i refinetext-to-3d-preview: tylko zadania previewtext-to-3d-refine: tylko zadania refineimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
Status do uwzględnienia,
SUCCEEDEDlubFAILED. Pomiń ten parametr, aby uwzględnić oba. Jakakolwiek inna wartość zwraca400.
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 rekorduimage-to-3d.
- Name
- endpoint
- Type
- string
- Description
Punkt końcowy, na którym wykonano zadanie, na przykład
image-to-3dlubrig. Zadanie Tekst na 3D pokazuje swój etap,text-to-3d-previewlubtext-to-3d-refine.Starsze rekordy mogą zawierać nazwy wycofanych punktów końcowych, których filtr
endpointsnie akceptuje.
- Name
- status
- Type
- string
- Description
Ostateczny status zadania,
SUCCEEDEDlubFAILED.
- 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.
0dla 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_namejest pusty, oraz dla logowań aplikacją, takich jak Meshy CLI.
- Name
- metadata
- Type
- object
- Description
Tagi wysłane w nagłówku
X-Meshy-Metadataw momencie utworzenia zadania.{}, jeśli ich brak. Zobacz Metadata.