Usage API
Vypište dokončené API úlohy vašeho týmu a kredity, které každá z nich spotřebovala, pro fakturační exporty a reporty nákladů.
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 správci. S jakýmkoli jiným API klíčem vrátí požadavek 403.
Výpis záznamů o využití
Vrátí jednu stránku záznamů o využití 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 se stavem
SUCCEEDEDneboFAILED - Úlohy každého současného člena týmu, z kteréhokoli jeho API klíče
- Úlohy, které jste smazali, a úlohy, jejichž soubory vypršely
Záznamy vynechávají tyto úlohy:
- Úlohy, které jsou stále
PENDINGneboIN_PROGRESS, a úlohy se stavemCANCELED - Úlohy osob, které tým opustily
- Úlohy Creative Lab
- Úlohy, které spustili AI agenti Meshy
- Práci provedenou ve webové aplikaci Meshy
Úloha se v záznamech objeví až poté, co skončí, v časovém okně podle jejího created_at. Meshy účtuje kredity v okamžiku vytvoření úlohy, takže úloha, která stále běží, v záznamech chybí. Než budete záznamy porovnávat se svým zůstatkem kreditů, znovu načtěte nedávná časová okna nebo exportujte s malým zpožděním.
Pokud má váš tým nastavenou dobu uchovávání dat, okno nezačíná dříve, než tato doba dovoluje.
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
- výchozí 1
- Description
Stránka, která se má vrátit, od
1do255. Hodnota nad255vrátí400. Jedno časové okno obsahuje nejvýše 255 stránek, takže velký export rozdělte na kratší okna.
- Name
- page_size
- Type
- integer
- výchozí 10
- Description
Počet záznamů na stránku, od
1do100. Hodnota od101do255vrátí 100 záznamů a hodnota nad255vrátí400.
- Name
- sort_by
- Type
- string
- výchozí -created_at
- Description
Pořadí řazení.
Dostupné hodnoty:
+created_at: od nejstarších-created_at: od nejnovějších
V URL zapište
+jako%2B. Jinak je+interpretováno jako mezera a požadavek vrátí400.
- Name
- start_time
- Type
- string
- Description
Začátek časového 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ředend_time.Okno může pokrývat nejvýše 366 dní. Delší okno vrátí
400, takže delší export rozdělte na několik oken.
- Name
- end_time
- Type
- string
- Description
Konec časového 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 refinetext-to-3d-preview: pouze úlohy previewtext-to-3d-refine: pouze úlohy refineimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
Stav, který se má zahrnout,
SUCCEEDEDneboFAILED. Pokud jej vynecháte, zahrnou se oba. Jakákoli jiná hodnota vrátí400.
Návratová hodnota
Vrátí pole záznamů o využití. Pole je prázdné, pokud žádné záznamy neodpovídají.
Chybové stavy
- Name
400 - Bad Request- Description
Některý parametr je neplatný a chybová zpráva uvádí který. Opravte parametr a odešlete požadavek znovu.
- Name
401 - Unauthorized- Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku
Authorization.
- Name
403 - Forbidden- Description
Účet 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-Aftera poté to zkuste znovu.
Objekt záznamu o využití
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, které vrátil koncový bod při jejím vytvoření. Pro získání samotné úlohy, včetně URL výstupů, odešlete toto ID na get route daného koncového bodu, například
GET /openapi/v1/image-to-3d/{task_id}pro záznamimage-to-3d.
- Name
- endpoint
- Type
- string
- Description
Koncový bod, na kterém úloha běžela, například
image-to-3dneborig. Úloha Text na 3D zobrazuje svou fázi,text-to-3d-previewnebotext-to-3d-refine.Starší záznamy mohou obsahovat názvy zrušených koncových bodů, které filtr
endpointsnepřijímá.
- Name
- status
- Type
- string
- Description
Konečný stav úlohy,
SUCCEEDEDneboFAILED.
- 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 vrácení prostředků.
0u neúspěšné úlohy, protože Meshy ji vrátí, a u bezplatné úlohy, jako je Analyzovat tisknutelnost.
- Name
- api_key_name
- Type
- string
- Description
Název API klíče, který úlohu spustil. U úlohy spuštěné přihlášením přes aplikaci je to název aplikace, například
Meshy CLI.V některých případech je to prázdný řetězec, například:
- Za úlohu nikdy nebylo účtováno, například u úlohy Analyzovat tisknutelnost, která je zdarma.
- API klíč byl smazán.
- API klíč byl vytvořen před několika minutami.
- Name
- api_key_suffix
- Type
- string
- Description
Poslední čtyři znaky daného API klíče, pro rozlišení klíčů se stejným názvem. Prázdný řetězec vždy, když je
api_key_nameprázdné, a u přihlášení přes aplikace, jako je Meshy CLI.
- Name
- metadata
- Type
- object
- Description
Značky odeslané v hlavičce
X-Meshy-Metadatapři vytvoření úlohy.{}, pokud žádné nejsou. Viz Metadata.