lowpoly จะยุติการให้บริการในวันที่ 30 ต.ค. 2569 meshy-7 ในฐานะโมเดลสร้าง 3D จะยุติการให้บริการในวันที่ 31 ธ.ค. 2569 แต่ยังใช้เป็นโมเดลเท็กซ์เจอร์ได้ตามเดิม โปรดเปลี่ยนโมเดลก่อนวันที่เหล่านี้เพื่อหลีกเลี่ยงข้อผิดพลาดของคำขอ ดูการเลิกใช้งานทั้งหมด

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 เอเจนต์ของ 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
    • relief
  • 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