Usage API

Vypište dokončené API úlohy vašeho týmu a počet kreditů, které každá z nich spotřebovala, pro účely fakturačních exportů a nákladových přehledů.

Pro volání tohoto koncového bodu použijte API klíč aktivního člena týmu Studio nebo Enterprise. Volat jej může kterýkoli člen, nejen vlastníci a administrátoři. S jakýmkoli jiným API klíčem vrátí požadavek 403.

GET/openapi/v1/usage/tasks

Seznam záznamů o spotřebě

Vrátí jednu stránku záznamů o spotřebě vašeho týmu, ve výchozím nastavení od nejnovějších. Bez start_time a end_time záznamy pokrývají posledních 30 dní. Volání tohoto koncového bodu je zdarma.

Záznamy zahrnují tyto úlohy:

API úlohy, které skončily jako SUCCEEDED nebo FAILED
Úlohy každého současného člena týmu, z libovolného z jeho API klíčů
Úlohy, které jste smazali, a úlohy, jejichž soubory vypršely

Záznamy nezahrnují tyto úlohy:

Úlohy, které jsou stále PENDING nebo IN_PROGRESS, a úlohy CANCELED
Úlohy lidí, kteří tým opustili
Úlohy Creative Lab
Úlohy, které spustili AI agenti Meshy
Práci provedenou ve webové aplikaci Meshy

Úloha se v záznamech objeví až po dokončení, v okně odpovídajícím jejímu created_at. Meshy účtuje kredity v okamžiku vytvoření úlohy, takže úloha, která ještě běží, v záznamech chybí. Než budete záznamy porovnávat se svým zůstatkem kreditů, znovu načtěte nedávná okna, nebo export proveďte s krátkým zpožděním.

Pokud má váš tým nastavenu dobu uchovávání dat, okno nezačíná dříve, než tato doba umožňuje.

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
výchozí 1
Description
Stránka, která se má vrátit, od 1 do 255. Hodnota vyšší než 255 vrátí 400. Jedno okno pojme nejvýše 255 stránek, takže velký export rozdělte do kratších oken.
Name
page_size
Type
integer
výchozí 10
Description
Počet záznamů na stránku, od 1 do 100. Hodnota od 101 do 255 vrátí 100 záznamů a hodnota vyšší než 255 vrátí 400.
Name
sort_by
Type
string
výchozí -created_at
Description
Pořadí řazení.
Dostupné hodnoty:
- +created_at: od nejstaršího
- -created_at: od nejnovějšího
V URL zapisujte + jako %2B. Jinak je + interpretováno jako mezera a požadavek vrátí 400.
Name
start_time
Type
string
Description
Začátek okna, jako časové razítko ve formátu RFC 3339, například 2026-08-01T00:00:00Z. Záznamy zahrnují úlohy vytvořené v tomto čase nebo později. Pokud jej vynecháte, okno začne 30 dní před end_time.
Okno může pokrývat nejvýše 366 dní. Delší okno vrátí 400, takže delší export rozdělte do několika oken.
Name
end_time
Type
string
Description
Konec okna, jako časové razítko ve formátu RFC 3339. Záznamy zahrnují úlohy vytvořené před tímto časem. Pokud jej vynecháte, okno skončí v čase vašeho požadavku.
Name
endpoints
Type
string
Description
Seznam koncových bodů oddělených čárkami, které se mají zahrnout, pod stejnými názvy jako pole endpoint. Pokud jej vynecháte, zahrnou se všechny koncové body. Neznámý název vrátí 400.
Dostupné hodnoty:
- text-to-3d: všechny úlohy Text na 3D, preview i refine
- text-to-3d-preview: pouze úlohy preview
- text-to-3d-refine: pouze úlohy 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
Stav, který se má zahrnout, SUCCEEDED nebo FAILED. Pokud jej vynecháte, zahrnou se oba. Jakákoli jiná hodnota vrátí 400.

Návratová hodnota

Vrátí pole záznamů o spotřebě. Pole je prázdné, pokud žádné záznamy neodpovídají.

Chybové stavy

Name
400 - Bad Request
Description
Parametr je neplatný a chybová zpráva uvádí který. Opravte parametr a požadavek odešlete znovu.
Name
401 - Unauthorized
Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.
Name
403 - Forbidden
Description
Účet daného API klíče není aktivním členem týmu Studio nebo Enterprise. Zpráva zní This endpoint is available on Studio and Enterprise plans. Použijte API klíč člena týmu Studio nebo Enterprise.
Name
429 - Too Many Requests
Description
Odeslali jste příliš mnoho požadavků. Počkejte počet sekund uvedený v Retry-After a zkuste to znovu.

Objekt záznamu o spotřebě

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
ID úlohy, stejné ID, jaké vrátil koncový bod, který ji vytvořil. Chcete-li získat samotnou úlohu s jejími výstupními URL adresami, pošlete toto ID na get route daného koncového bodu, například GET /openapi/v1/image-to-3d/{task_id} pro záznam image-to-3d.
Name
endpoint
Type
string
Description
Koncový bod, na kterém úloha běžela, například image-to-3d nebo rig. Úloha Text na 3D zobrazuje svou fázi, text-to-3d-preview nebo text-to-3d-refine.
Starší záznamy mohou obsahovat názvy zrušených koncových bodů, které filtr endpoints nepřijímá.
Name
status
Type
string
Description
Konečný stav úlohy, SUCCEEDED nebo FAILED.
Name
created_at
Type
timestamp
Description
Čas vytvoření úlohy, v milisekundách Unixového času.
Name
finished_at
Type
timestamp
Description
Čas dokončení úlohy, v milisekundách Unixového času. null, pokud úloha nemá čas dokončení.
Name
consumed_credits
Type
integer
Description
Počet kreditů, které úloha spotřebovala, po zohlednění vrácení. 0 u neúspěšné úlohy, protože Meshy kredity vrátí, a také u bezplatné úlohy, jako je Analyzovat tisknutelnost.
Name
api_key_name
Type
string
Description
Název API klíče, pod kterým úloha běžela. U úlohy spuštěné přihlášením přes aplikaci je to název dané aplikace, například Meshy CLI.
V některých případech jde o prázdný řetězec, například:
- Úloha nebyla nikdy zpoplatněna, například úloha Analyzovat tisknutelnost, která je zdarma.
- API klíč byl smazán.
- API klíč byl vytvořen v posledních několika minutách.
Name
api_key_suffix
Type
string
Description
Poslední čtyři znaky daného API klíče, pro odlišení klíčů se stejným názvem. Prázdný řetězec vždy, když je api_key_name prázdné, a u přihlášení přes aplikace, jako je Meshy CLI.
Name
metadata
Type
object
Description
Štítky odeslané v hlavičce X-Meshy-Metadata při vytvoření úlohy. {}, pokud žádné nejsou. Viz Metadata.