Usage API

Usage API vrací historické API úlohy vašeho týmu spolu s kredity, které každá z nich spotřebovala. Filtrujte podle časového okna, koncového bodu nebo stavu a procházejte výsledky po stránkách pro hromadný export.

Dostupnost. API klíč musí patřit týmu na plánu Studio nebo Enterprise; klíče na jakémkoli jiném plánu, nebo bez týmu, obdrží 403.

GET/openapi/v1/usage/tasks

List Usage Records

Vrací jednu stránku API úloh týmu, seřazených od nejnovějších. Bez explicitně zadaného časového rozsahu pokrývá odpověď posledních 30 dní.

Parametry

Name
page_num
Type
integer
výchozí 1
Description
Číslo stránky pro stránkování.
Name
page_size
Type
integer
výchozí 10
Description
Limit velikosti stránky. Maximální povolená hodnota je 100 položek.
Name
sort_by
Type
string
výchozí -created_at
Description
Pole, podle kterého se má řadit.
Dostupné hodnoty:
- +created_at: Řadit podle času vytvoření vzestupně.
- -created_at: Řadit podle času vytvoření sestupně.
Name
start_time
Type
string
Description
Začátek okna created_at, jako časové razítko RFC 3339 (např. 2026-08-01T00:00:00Z). Výchozí hodnota je 30 dní před end_time. Okno může pokrývat nanejvýš 1 rok — pro větší exporty procházejte po sobě jdoucí okna.
Name
end_time
Type
string
Description
Konec okna created_at, jako časové razítko RFC 3339. Výchozí hodnota je aktuální čas.
Name
endpoints
Type
string
Description
Seznam názvů koncových bodů oddělených čárkami, které se mají zahrnout. Přijímá stejné hodnoty, jaké nese pole odpovědi endpoint — text-to-3d, text-to-3d-preview, text-to-3d-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 — přičemž text-to-3d je souhrnná hodnota pokrývající jak fázi preview, tak fázi refine. Vynechte, chcete-li zahrnout všechny koncové body.
Name
status
Type
string
Description
Filtrovat podle konečného stavu úlohy: SUCCEEDED nebo FAILED. Vynechte, chcete-li zahrnout oba.

Vrací

Vrací stránkovaný seznam The Usage Record Objects.

Záznamy pokrývají úlohy, které dosáhly konečného stavu. Kredity se účtují v okamžiku vytvoření úlohy, takže úloha, která při exportu ještě běží, není ještě v tomto okně výsledků obsažena — pokud vaše celkové součty musí přesně odpovídat vašemu zůstatku kreditů, znovu stáhněte nedávná okna (nebo exportujte s krátkým zpožděním).

Týmy s vlastní zásadou uchovávání dat obdrží záznamy v rámci jimi nastaveného okna uchovávání.

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

The Usage Record Object

Name
task_id
Type
string
Description
ID úlohy, kterou tento záznam účtuje — stejné ID, jaké vrátil koncový bod při vytvoření. Chcete-li získat úlohu samotnou (včetně jejího výstupního modelu nebo URL adres obrázků, znovu podepsaných při každém čtení), předejte toto ID odpovídajícímu koncovému bodu pro načtení, např. GET /openapi/v1/{endpoint}/{task_id}.
Name
endpoint
Type
string
Description
Koncový bod, na kterém úloha běžela, např. image-to-3d nebo text-to-3d-refine. Úlohy Text na 3D uvádějí svou fázi (text-to-3d-preview / text-to-3d-refine).
Name
status
Type
string
Description
Konečný stav úlohy: SUCCEEDED nebo FAILED.
Name
created_at
Type
timestamp
Description
Časové razítko vytvoření úlohy, v milisekundách.
Name
finished_at
Type
timestamp
Description
Časové razítko dokončení, v milisekundách. null, pokud úloha nenese žádný čas dokončení.
Name
consumed_credits
Type
integer
Description
Kredity spotřebované touto úlohou. Vrací 0 u úloh se stavem FAILED (při selhání jsou kredity vráceny).
Name
api_key_name
Type
string
Description
Zobrazovaný název API klíče, který úlohu spustil. Zůstává vyplněný i u odvolaných klíčů, takže historické výdaje zůstávají přiřaditelné i po obměně klíčů.
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.

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"
}