Usage API

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

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

GET/openapi/v1/usage/tasks

List Usage Records

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

พารามิเตอร์

  • Name
    page_num
    Type
    integer
    ค่าเริ่มต้น 1
    Description

    หมายเลขหน้าสำหรับการแบ่งหน้า

  • Name
    page_size
    Type
    integer
    ค่าเริ่มต้น 10
    Description

    จำนวนรายการสูงสุดต่อหน้า สูงสุดที่รองรับคือ 100 รายการ

  • Name
    sort_by
    Type
    string
    ค่าเริ่มต้น -created_at
    Description

    ฟิลด์ที่ใช้เรียงลำดับ

    ค่าที่ใช้ได้:

    • +created_at: เรียงตามเวลาที่สร้างจากน้อยไปมาก
    • -created_at: เรียงตามเวลาที่สร้างจากมากไปน้อย
  • Name
    start_time
    Type
    string
    Description

    จุดเริ่มต้นของช่วงเวลา created_at ในรูปแบบไทม์สแตมป์ RFC 3339 (เช่น 2026-08-01T00:00:00Z) ค่าเริ่มต้นคือ 30 วันก่อน end_time ช่วงเวลาสามารถกว้างได้สูงสุด 1 ปี — สำหรับการส่งออกข้อมูลจำนวนมาก ให้แบ่งหน้าไล่ทีละช่วงเวลาต่อเนื่องกัน

  • Name
    end_time
    Type
    string
    Description

    จุดสิ้นสุดของช่วงเวลา created_at ในรูปแบบไทม์สแตมป์ RFC 3339 ค่าเริ่มต้นคือเวลาปัจจุบัน

  • Name
    endpoints
    Type
    string
    Description

    รายชื่อเอนด์พอยต์ที่ต้องการรวม คั่นด้วยจุลภาค รองรับค่าเดียวกับที่ฟิลด์ 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 — โดย text-to-3d เป็นชื่อรวมที่ครอบคลุมทั้งขั้นตอน preview และ refine ไม่ต้องระบุหากต้องการรวมทุกเอนด์พอยต์

  • Name
    status
    Type
    string
    Description

    กรองตามสถานะสิ้นสุดของงาน: SUCCEEDED หรือ FAILED ไม่ต้องระบุหากต้องการรวมทั้งสองสถานะ

สิ่งที่ส่งคืน

ส่งคืนรายการแบบแบ่งหน้าของ The Usage Record Objects

รายการนี้ครอบคลุมเฉพาะงานที่ถึงสถานะสิ้นสุดแล้ว เครดิตจะถูกหักเมื่อสร้างงาน ดังนั้นงานที่ยังทำงานอยู่ขณะที่คุณส่งออกข้อมูลจะยังไม่ปรากฏในผลลัพธ์ของช่วงเวลานั้น — ลองดึงข้อมูลช่วงเวลาล่าสุดซ้ำอีกครั้ง (หรือส่งออกโดยหน่วงเวลาสักครู่) หากยอดรวมของคุณต้องตรงกับยอดคงเหลือเครดิตแบบเป๊ะ ๆ

ทีมที่มีนโยบายการเก็บรักษาข้อมูลแบบกำหนดเอง จะได้รับรายการภายในช่วงเวลาการเก็บรักษาที่ตั้งค่าไว้

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 ของงานที่รายการนี้เรียกเก็บเงิน — เป็น ID เดียวกับที่เอนด์พอยต์ที่สร้างงานส่งคืนมา หากต้องการดึงข้อมูลงานนั้นโดยตรง (รวมถึง URL ของโมเดลหรือรูปภาพผลลัพธ์ ซึ่งจะถูกเซ็นใหม่ทุกครั้งที่อ่าน) ให้ส่งค่านี้ไปยังเอนด์พอยต์สำหรับดึงข้อมูลที่เกี่ยวข้อง เช่น GET /openapi/v1/{endpoint}/{task_id}

  • Name
    endpoint
    Type
    string
    Description

    เอนด์พอยต์ที่งานนี้ทำงานอยู่ เช่น image-to-3d หรือ text-to-3d-refine งานประเภทข้อความเป็น 3D จะรายงานขั้นตอนของตัวเอง (text-to-3d-preview / text-to-3d-refine)

  • Name
    status
    Type
    string
    Description

    สถานะสิ้นสุดของงาน: SUCCEEDED หรือ FAILED

  • Name
    created_at
    Type
    timestamp
    Description

    ไทม์สแตมป์ของเวลาที่สร้างงาน หน่วยเป็นมิลลิวินาที

  • Name
    finished_at
    Type
    timestamp
    Description

    ไทม์สแตมป์ของเวลาที่เสร็จสิ้น หน่วยเป็นมิลลิวินาที เป็น null หากงานนั้นไม่มีเวลาสิ้นสุด

  • Name
    consumed_credits
    Type
    integer
    Description

    จำนวนเครดิตที่งานนี้ใช้ไป จะส่งคืนค่า 0 สำหรับงานที่มีสถานะ FAILED (เครดิตจะถูกคืนเมื่อล้มเหลว)

  • Name
    api_key_name
    Type
    string
    Description

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

  • Name
    api_key_suffix
    Type
    string
    Description

    อักขระสี่ตัวสุดท้ายของ API คีย์นั้น ใช้เพื่อแยกความแตกต่างระหว่างคีย์ที่มีชื่อเดียวกัน

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