Usage API

แสดงรายการ API tasks ที่เสร็จสิ้นแล้วของทีมคุณและเครดิตที่แต่ละงานใช้ไป สำหรับการส่งออกข้อมูลการเรียกเก็บเงินและรายงานต้นทุน

ในการเรียกเอนด์พอยต์นี้ ให้ใช้ API คีย์ของสมาชิกที่ยังใช้งานอยู่ในทีม Studio หรือ Enterprise สมาชิกคนใดก็ได้สามารถเรียกเอนด์พอยต์นี้ ไม่จำกัดเฉพาะเจ้าของและผู้ดูแลระบบ หากใช้ API คีย์อื่นที่ไม่เข้าเงื่อนไขนี้ คำขอจะได้รับการตอบกลับเป็น 403

GET/openapi/v1/usage/tasks

แสดงรายการประวัติการใช้งาน

ส่งคืนประวัติการใช้งานของทีมคุณหนึ่งหน้า โดยค่าเริ่มต้นจะเรียงจากใหม่ไปเก่า หากไม่ระบุ start_time และ end_time ประวัติจะครอบคลุม 30 วันที่ผ่านมา การเรียกเอนด์พอยต์นี้ไม่มีค่าใช้จ่าย

ประวัติจะรวมงานเหล่านี้:

API tasks ที่เสร็จสิ้นด้วยสถานะ SUCCEEDED หรือ FAILED
งานของสมาชิกทุกคนที่อยู่ในทีมปัจจุบัน จาก API คีย์ใดก็ได้ของพวกเขา
งานที่คุณลบไปแล้ว และงานที่ไฟล์หมดอายุไปแล้ว

ประวัติจะไม่รวมงานเหล่านี้:

งานที่ยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS และงานที่มีสถานะ CANCELED
งานของผู้ที่ออกจากทีมไปแล้ว
งานใน Creative Lab
งานที่ AI agent ของ Meshy เป็นผู้ดำเนินการ
งานที่ทำในเว็บแอปของ Meshy

งานหนึ่งจะปรากฏในประวัติก็ต่อเมื่อเสร็จสิ้นแล้วเท่านั้น โดยอยู่ในช่วงเวลาของ created_at ของงานนั้น Meshy จะหักเครดิตตอนที่สร้างงาน ดังนั้นงานที่ยังทำงานอยู่จะยังไม่ปรากฏในประวัติ ก่อนที่คุณจะกระทบยอดประวัติกับยอดเครดิตคงเหลือ ให้ดึงข้อมูลในช่วงเวลาล่าสุดอีกครั้ง หรือส่งออกข้อมูลหลังจากรอสักครู่

หากทีมของคุณมีระยะเวลาการเก็บรักษาข้อมูล ช่วงเวลาจะเริ่มต้นได้ไม่เร็วกว่าที่ระยะเวลานั้นอนุญาต

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

พารามิเตอร์

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 และ refine
- text-to-3d-preview: เฉพาะงาน preview
- text-to-3d-refine: เฉพาะงาน 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
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 ของเอนด์พอยต์นั้น เช่น 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 milliseconds
Name
finished_at
Type
timestamp
Description
เวลาที่งานเสร็จสิ้น ในหน่วย Unix milliseconds เป็น 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