Usage API

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

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

GET/openapi/v1/usage/tasks

List Usage Records

ส่งคืนผลลัพธ์หนึ่งหน้าของทาสก์ API ของทีม เรียงจากใหม่สุดไปเก่าสุด หากไม่ระบุช่วงเวลา คำตอบจะครอบคลุม 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"
}