Usage API
แสดงรายการ API tasks ที่เสร็จสิ้นแล้วของทีมของคุณ และจำนวนเครดิตที่แต่ละงานใช้ไป สำหรับการส่งออกข้อมูลเพื่อการเรียกเก็บเงินและรายงานต้นทุน
ในการเรียกเอนด์พอยต์นี้ ให้ใช้ API คีย์ของสมาชิกที่ยังใช้งานอยู่ของทีม Studio หรือ Enterprise สมาชิกคนใดก็ได้สามารถเรียกใช้ได้ ไม่จำกัดเฉพาะเจ้าของและผู้ดูแลระบบ หากใช้ API คีย์อื่นใด คำขอจะส่งคืนค่า 403
แสดงรายการประวัติการใช้งาน
ส่งคืนประวัติการใช้งานของทีมคุณหนึ่งหน้า เรียงจากล่าสุดไปเก่าสุดเป็นค่าเริ่มต้น หากไม่ระบุ start_time และ end_time ประวัติจะครอบคลุม 30 วันที่ผ่านมา การเรียกเอนด์พอยต์นี้ไม่มีค่าใช้จ่าย
ประวัติจะรวมงานเหล่านี้ไว้ด้วย:
- API tasks ที่เสร็จสิ้นด้วยสถานะ
SUCCEEDEDหรือFAILED - งานของสมาชิกปัจจุบันทุกคนในทีม จาก API คีย์ใดๆ ของพวกเขา
- งานที่คุณลบไปแล้ว และงานที่ไฟล์หมดอายุไปแล้ว
ประวัติจะไม่รวมงานเหล่านี้:
- งานที่ยังเป็น
PENDINGหรือIN_PROGRESSและงานที่เป็นCANCELED - งานของคนที่ออกจากทีมไปแล้ว
- งานใน Creative Lab
- งานที่ AI เอเจนต์ของ Meshy เป็นผู้รัน
- งานที่ทำในเว็บแอป Meshy
งานหนึ่งจะปรากฏในประวัติก็ต่อเมื่อเสร็จสิ้นแล้วเท่านั้น โดยอยู่ในช่วงเวลาของ created_at ของงานนั้น Meshy จะเรียกเก็บเครดิตเมื่อสร้างงาน ดังนั้นงานที่ยังทำงานอยู่จะยังไม่ปรากฏในประวัติ ก่อนที่คุณจะกระทบยอดประวัติกับยอดคงเหลือเครดิตของคุณ ให้ดึงข้อมูลช่วงเวลาล่าสุดอีกครั้ง หรือส่งออกข้อมูลหลังจากรอสักครู่
หากทีมของคุณมีระยะเวลาการเก็บรักษาข้อมูล ช่วงเวลาจะเริ่มต้นไม่เร็วกว่าที่ระยะเวลานั้นอนุญาต
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": {}
}
]
พารามิเตอร์
- Name
- page_num
- Type
- integer
- ค่าเริ่มต้น 1
- Description
หน้าที่จะส่งคืน ตั้งแต่
1ถึง255ค่าที่สูงกว่า255จะส่งคืน400หนึ่งช่วงเวลาสามารถมีได้สูงสุด 255 หน้า ดังนั้นให้แบ่งการส่งออกข้อมูลขนาดใหญ่ออกเป็นช่วงเวลาที่สั้นลง
- Name
- page_size
- Type
- integer
- ค่าเริ่มต้น 10
- Description
จำนวนรายการต่อหน้า ตั้งแต่
1ถึง100ค่าตั้งแต่101ถึง255จะส่งคืน 100 รายการ และค่าที่สูงกว่า255จะส่งคืน400
- Name
- sort_by
- Type
- string
- ค่าเริ่มต้น -created_at
- Description
ลำดับการเรียง
ค่าที่ใช้ได้:
+created_at: เก่าสุดก่อน-created_at: ล่าสุดก่อน
ในURL ให้เขียน
+เป็น%2Bไม่เช่นนั้น+จะถูกตีความเป็นช่องว่าง และคำขอจะส่งคืน400
- Name
- start_time
- Type
- string
- Description
จุดเริ่มต้นของช่วงเวลา ในรูปแบบไทม์สแตมป์ RFC 3339 ตัวอย่างเช่น
2026-08-01T00:00:00Zประวัติจะรวมงานที่สร้างขึ้นในเวลานี้หรือหลังจากนั้น หากไม่ระบุ ช่วงเวลาจะเริ่มต้น 30 วันก่อนend_timeช่วงเวลาสามารถครอบคลุมได้สูงสุด 366 วัน ช่วงเวลาที่ยาวกว่านี้จะส่งคืน
400ดังนั้นให้แบ่งการส่งออกข้อมูลที่ยาวกว่าออกเป็นหลายช่วงเวลา
- Name
- end_time
- Type
- string
- Description
จุดสิ้นสุดของช่วงเวลา ในรูปแบบไทม์สแตมป์ RFC 3339 ประวัติจะรวมงานที่สร้างขึ้นก่อนเวลานี้ หากไม่ระบุ ช่วงเวลาจะสิ้นสุดที่เวลาที่คุณส่งคำขอ
- Name
- endpoints
- Type
- string
- Description
รายการเอนด์พอยต์ที่จะรวม คั่นด้วยเครื่องหมายจุลภาค โดยใช้ชื่อเดียวกับฟิลด์
endpointหากไม่ระบุ จะรวมทุกเอนด์พอยต์ ชื่อที่ไม่รู้จักจะส่งคืน400ค่าที่ใช้ได้:
text-to-3d: ทุกงานข้อความเป็น 3D ทั้ง preview และ refinetext-to-3d-preview: เฉพาะงาน previewtext-to-3d-refine: เฉพาะงาน refineimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- Name
- status
- Type
- string
- Description
สถานะที่จะรวม
SUCCEEDEDหรือFAILEDหากไม่ระบุ จะรวมทั้งสองสถานะ ค่าอื่นใดจะส่งคืน400
ส่งคืนค่า
ส่งคืนอาร์เรย์ของประวัติการใช้งาน อาร์เรย์จะว่างเปล่าเมื่อไม่มีรายการที่ตรงกัน
รูปแบบความล้มเหลว
- Name
400 - Bad Request- Description
พารามิเตอร์ไม่ถูกต้อง และข้อความแสดงข้อผิดพลาดจะระบุว่าเป็นพารามิเตอร์ตัวใด ให้แก้ไขพารามิเตอร์ แล้วส่งคำขออีกครั้ง
- Name
401 - Unauthorized- Description
API คีย์หายไปหรือไม่ถูกต้อง ตรวจสอบเฮดเดอร์
Authorization
- Name
403 - Forbidden- Description
บัญชีของ API คีย์ไม่ใช่สมาชิกที่ยังใช้งานอยู่ของทีม Studio หรือ Enterprise ข้อความคือ
This endpoint is available on Studio and Enterprise plansให้ใช้ API คีย์ของสมาชิกทีม Studio หรือ Enterprise
- Name
429 - Too Many Requests- Description
คุณส่งคำขอมากเกินไป ให้รอตามจำนวนวินาทีใน
Retry-Afterแล้วลองใหม่
ออบเจ็กต์ประวัติการใช้งาน
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
ไอดีของงาน ซึ่งเป็นไอดีเดียวกับที่เอนด์พอยต์ผู้สร้างส่งคืนมา ในการดึงข้อมูลงานนั้นพร้อม URL ผลลัพธ์ ให้ส่งไอดีไปยัง get route ของเอนด์พอยต์นั้น ตัวอย่างเช่น
GET /openapi/v1/image-to-3d/{task_id}สำหรับประวัติของimage-to-3d
- Name
- endpoint
- Type
- string
- Description
เอนด์พอยต์ที่งานนั้นรันอยู่ ตัวอย่างเช่น
image-to-3dหรือrigงานข้อความเป็น 3D จะแสดงขั้นตอนของมัน คือtext-to-3d-previewหรือtext-to-3d-refineประวัติเก่าๆ อาจมีชื่อของเอนด์พอยต์ที่เลิกใช้งานแล้ว ซึ่งตัวกรอง
endpointsไม่ยอมรับ
- Name
- status
- Type
- string
- Description
สถานะสุดท้ายของงาน
SUCCEEDEDหรือFAILED
- Name
- created_at
- Type
- timestamp
- Description
เวลาที่สร้างงาน ในหน่วยมิลลิวินาที Unix
- Name
- finished_at
- Type
- timestamp
- Description
เวลาที่งานเสร็จสิ้น ในหน่วยมิลลิวินาที Unix
nullหากงานนั้นไม่มีเวลาเสร็จสิ้น
- Name
- consumed_credits
- Type
- integer
- Description
จำนวนเครดิตที่งานใช้ไป หลังจากการคืนเงิน
0สำหรับงานที่ล้มเหลว เนื่องจาก Meshy คืนเครดิตให้ และสำหรับงานที่ไม่มีค่าใช้จ่าย เช่น วิเคราะห์ความสามารถในการพิมพ์
- Name
- api_key_name
- Type
- string
- Description
ชื่อของ API คีย์ที่รันงานนั้น สำหรับงานที่รันด้วยการล็อกอินผ่านแอป จะเป็นชื่อของแอปนั้น ตัวอย่างเช่น
Meshy CLIจะเป็นสตริงว่างในบางกรณี ตัวอย่างเช่น:
- งานนั้นไม่เคยถูกเรียกเก็บเงิน เช่น งานวิเคราะห์ความสามารถในการพิมพ์ ซึ่งไม่มีค่าใช้จ่าย
- API คีย์นั้นถูกลบไปแล้ว
- API คีย์นั้นถูกสร้างขึ้นเมื่อไม่กี่นาทีที่ผ่านมา
- Name
- api_key_suffix
- Type
- string
- Description
อักขระสี่ตัวสุดท้ายของ API คีย์นั้น เพื่อแยกความแตกต่างระหว่างคีย์ที่มีชื่อเดียวกัน จะเป็นสตริงว่างเมื่อใดก็ตามที่
api_key_nameว่างเปล่า และสำหรับการล็อกอินผ่านแอป เช่น Meshy CLI
- Name
- metadata
- Type
- object
- Description
แท็กที่ส่งในเฮดเดอร์
X-Meshy-Metadataเมื่อสร้างงานนั้น{}หากไม่มี ดู Metadata