lowpoly bude vyřazen 30. 10. 2026. meshy-7 bude jako model pro generování 3D vyřazen 31. 12. 2026; jako texturovací model zůstává k dispozici. Před těmito daty přejděte na jiný model, abyste předešli chybám požadavků. Zobrazit všechna ukončení podpory

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.


GET/openapi/v1/usage/tasks

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 SUCCEEDED nebo FAILED
  • Ú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 PENDING nebo IN_PROGRESS, a úlohy se stavem CANCELED
  • Ú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

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 nad 255 vrá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 1 do 100. Hodnota od 101 do 255 vrátí 100 záznamů a hodnota nad 255 vrá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řed end_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 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
    • relief
  • 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 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-After a 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á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 vrácení prostředků. 0 u 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_name prá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-Metadata při vytvoření úlohy. {}, pokud žádné nejsou. Viz Metadata.