Usage API
Ilista ang mga natapos na API task ng iyong team at ang credits na ginamit ng bawat isa, para sa billing exports at cost reports.
Para tawagin ang endpoint na ito, gumamit ng API key ng isang aktibong miyembro ng Studio o Enterprise team. Kahit sinong miyembro ang pwedeng tumawag nito, hindi lang ang mga owner at admin. Sa ibang API key, magbabalik ang request ng 403.
Ilista ang mga usage record
Nagbabalik ito ng isang pahina ng mga usage record ng iyong team, ang pinakabago muna bilang default. Kung walang start_time at end_time, sakop ng mga record ang huling 30 araw. Libre ang pagtawag sa endpoint na ito.
Kasama sa mga record ang mga sumusunod na task:
- Mga API task na natapos bilang
SUCCEEDEDoFAILED - Mga task ng bawat kasalukuyang miyembro ng team, mula sa alinman sa kanilang mga API key
- Mga task na dineliyt mo, at mga task na nag-expire na ang mga file
Hindi kasama sa mga record ang mga sumusunod na task:
- Mga task na
PENDINGoIN_PROGRESSpa, at mgaCANCELEDna task - Mga task ng mga taong umalis na sa team
- Mga task ng Creative Lab
- Mga task na pinatakbo ng mga AI agent ng Meshy
- Gawaing ginawa sa web app ng Meshy
Lalabas lamang ang isang task sa mga record pagkatapos itong matapos, sa loob ng window ng kanyang created_at. Sisingilin ng Meshy ang credits kapag gumawa ito ng task, kaya mawawala sa mga record ang isang task na tumatakbo pa. Bago mo i-reconcile ang mga record sa iyong credit balanse, kunin muli ang mga kamakailang window, o mag-export pagkatapos ng maikling pagkaantala.
Kung ang iyong team ay may data retention period, ang window ay magsisimula nang hindi mas maaga kaysa sa pinapayagan ng period na iyon.
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": {}
}
]
Mga Parameter
- Name
- page_num
- Type
- integer
- default 1
- Description
Ang pahinang ibabalik, mula
1hanggang255. Ang value na higit sa255ay magbabalik ng400. Ang isang window ay may hanggang 255 pahina, kaya hatiin ang malaking export sa mas maiikling window.
- Name
- page_size
- Type
- integer
- default 10
- Description
Bilang ng mga record kada pahina, mula
1hanggang100. Ang value na mula101hanggang255ay magbabalik ng 100 record, at ang value na higit sa255ay magbabalik ng400.
- Name
- sort_by
- Type
- string
- default -created_at
- Description
Ang pagkakasunod-sunod.
Mga available na value:
+created_at: pinakaluma muna-created_at: pinakabago muna
Sa URL, isulat ang
+bilang%2B. Kung hindi, mababasa ang+bilang espasyo, at magbabalik ang request ng400.
- Name
- start_time
- Type
- string
- Description
Ang simula ng window, bilang RFC 3339 timestamp, halimbawa
2026-08-01T00:00:00Z. Kasama sa mga record ang mga task na ginawa sa o pagkatapos ng oras na ito. Iwanan itong wala para magsimula ang window 30 araw bago angend_time.Ang window ay maaaring sumaklaw ng hanggang 366 araw. Ang mas mahabang window ay magbabalik ng
400, kaya hatiin ang mas mahabang export sa ilang window.
- Name
- end_time
- Type
- string
- Description
Ang dulo ng window, bilang RFC 3339 timestamp. Kasama sa mga record ang mga task na ginawa bago ang oras na ito. Iwanan itong wala para magtapos ang window sa oras ng iyong request.
- Name
- endpoints
- Type
- string
- Description
Isang listahan na pinaghihiwalay ng kuwit ng mga endpoint na isasama, gamit ang parehong mga pangalan tulad ng field na
endpoint. Iwanan itong wala para isama ang bawat endpoint. Ang hindi kilalang pangalan ay magbabalik ng400.Mga available na value:
text-to-3d: bawat Text to 3D task, preview at refinetext-to-3d-preview: mga preview task lamangtext-to-3d-refine: mga refine task lamangimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
Ang status na isasama,
SUCCEEDEDoFAILED. Iwanan itong wala para isama ang parehong dalawa. Ang anumang ibang value ay magbabalik ng400.
Ibinabalik
Nagbabalik ito ng isang array ng mga usage record. Walang laman ang array kapag walang tumutugmang record.
Mga paraan ng pagkabigo
- Name
400 - Bad Request- Description
May isang parameter na invalid, at sinasabi ng error message kung alin. Ayusin ang parameter, pagkatapos ay ipadala muli ang request.
- Name
401 - Unauthorized- Description
Nawawala o invalid ang API key. Suriin ang
Authorizationheader.
- Name
403 - Forbidden- Description
Ang account ng API key ay hindi isang aktibong miyembro ng Studio o Enterprise team. Ang mensahe ay
This endpoint is available on Studio and Enterprise plans. Gumamit ng API key ng isang miyembro ng Studio o Enterprise team.
- Name
429 - Too Many Requests- Description
Masyado kang maraming request ang ipinadala. Hintayin ang bilang ng segundo sa
Retry-After, pagkatapos ay subukan muli.
Usage record object
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
Ang task ID, ang parehong ID na ibinalik ng gumawang endpoint. Para makuha ang task mismo, kasama ang mga output URL nito, ipadala ang ID sa get route ng endpoint na iyon, halimbawa
GET /openapi/v1/image-to-3d/{task_id}para sa isangimage-to-3drecord.
- Name
- endpoint
- Type
- string
- Description
Ang endpoint kung saan tumakbo ang task, halimbawa
image-to-3dorig. Ipinapakita ng isang Text to 3D task ang kanyang yugto,text-to-3d-previewotext-to-3d-refine.Maaaring magkaroon ang mas lumang mga record ng mga pangalan ng retiradong endpoint, na hindi tinatanggap ng filter na
endpoints.
- Name
- status
- Type
- string
- Description
Ang pangwakas na status ng task,
SUCCEEDEDoFAILED.
- Name
- created_at
- Type
- timestamp
- Description
Oras na ginawa ang task, sa Unix milliseconds.
- Name
- finished_at
- Type
- timestamp
- Description
Oras na natapos ang task, sa Unix milliseconds.
nullkung walang oras ng pagkatapos ang task.
- Name
- consumed_credits
- Type
- integer
- Description
Bilang ng credits na ginamit ng task, pagkatapos ng mga refund.
0para sa isang nabigong task, dahil nire-refund ito ng Meshy, at para sa isang libreng task tulad ng Analyze Printability.
- Name
- api_key_name
- Type
- string
- Description
Ang pangalan ng API key na nagpatakbo ng task. Para sa isang task na pinatakbo gamit ang app login, ito ang pangalan ng app, halimbawa
Meshy CLI.Ito ay isang walang-lamang string sa ilang kaso, halimbawa:
- Hindi kailanman sinisingil ang task, tulad ng isang Analyze Printability task, na libre.
- Nadeliyt na ang API key.
- Nagawa lang ang API key nitong mga nakaraang ilang minuto.
- Name
- api_key_suffix
- Type
- string
- Description
Ang huling apat na karakter ng API key na iyon, para maiba ang mga key na may parehong pangalan. Isang walang-lamang string sa tuwing walang laman ang
api_key_name, at para sa mga app login tulad ng Meshy CLI.
- Name
- metadata
- Type
- object
- Description
Ang mga tag na ipinadala sa
X-Meshy-Metadataheader noong ginawa ang task.{}kung wala. Tingnan ang Metadata.