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