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, print-split — โดยที่ 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"
}