Usage API

Usage API, ekibinizin geçmiş API görevlerini ve her birinin tükettiği kredileri döndürür. Zaman aralığına, uç noktaya veya duruma göre filtreleyin ve sonuçları toplu dışa aktarmak için sayfalar arasında gezinin.

Kullanılabilirlik. API anahtarı bir Studio veya Enterprise ekibine ait olmalıdır; başka bir plana ait veya ekibi olmayan anahtarlar 403 yanıtı alır.

GET/openapi/v1/usage/tasks

List Usage Records

Ekibin API görevlerinin bir sayfasını, en yeniden en eskiye doğru döndürür. Açık bir zaman aralığı belirtilmezse, yanıt son 30 günü kapsar.

Parametreler

  • Name
    page_num
    Type
    integer
    varsayılan 1
    Description

    Sayfalama için sayfa numarası.

  • Name
    page_size
    Type
    integer
    varsayılan 10
    Description

    Sayfa boyutu sınırı. İzin verilen maksimum 100 öğedir.

  • Name
    sort_by
    Type
    string
    varsayılan -created_at
    Description

    Sıralama yapılacak alan.

    Kullanılabilir değerler:

    • +created_at: Oluşturulma zamanına göre artan sırada sırala.
    • -created_at: Oluşturulma zamanına göre azalan sırada sırala.
  • Name
    start_time
    Type
    string
    Description

    created_at aralığının başlangıcı, RFC 3339 zaman damgası olarak (ör. 2026-08-01T00:00:00Z). Varsayılan olarak end_time'dan 30 gün öncesidir. Aralık en fazla 1 yıl olabilir — daha büyük dışa aktarmalar için ardışık aralıklarda sayfalayın.

  • Name
    end_time
    Type
    string
    Description

    created_at aralığının sonu, RFC 3339 zaman damgası olarak. Varsayılan olarak geçerli zamandır.

  • Name
    endpoints
    Type
    string
    Description

    Dahil edilecek uç nokta adlarının virgülle ayrılmış listesi. endpoint yanıt alanının taşıdığı aynı değerleri kabul eder — 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 — burada text-to-3d, hem önizleme hem de rafine etme aşamalarını kapsayan bir şemsiye terimdir. Her uç noktayı dahil etmek için boş bırakın.

  • Name
    status
    Type
    string
    Description

    Nihai görev durumuna göre filtrele: SUCCEEDED veya FAILED. Her ikisini de dahil etmek için boş bırakın.

Döndürülenler

Usage Record Nesnelerinin sayfalanmış bir listesini döndürür.

Kayıtlar, nihai bir duruma ulaşmış görevleri kapsar. Krediler bir görev oluşturulduğunda tahsil edildiğinden, dışa aktarma sırasında hâlâ çalışmakta olan bir görev henüz o aralığın sonuçlarında yer almaz — toplamlarınızın kredi bakiyenizle tam olarak eşleşmesi gerekiyorsa yakın zamanlı aralıkları yeniden çekin (veya kısa bir gecikmeyle dışa aktarın).

Özel bir veri saklama politikasına sahip ekipler, yapılandırılmış saklama pencereleri içindeki kayıtları alır.

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

    Bu kaydın faturalandırdığı görevin ID'si — oluşturan uç noktanın döndürdüğü aynı ID. Görevin kendisini (yeniden imzalanmış çıktı modeli veya görsel URL'leri her okuma işleminde dahil olmak üzere) almak için, bunu ilgili getirme uç noktasına iletin, ör. GET /openapi/v1/{endpoint}/{task_id}.

  • Name
    endpoint
    Type
    string
    Description

    Görevin çalıştığı uç nokta, ör. image-to-3d veya text-to-3d-refine. Text to 3D görevleri, aşamalarını raporlar (text-to-3d-preview / text-to-3d-refine).

  • Name
    status
    Type
    string
    Description

    Nihai görev durumu: SUCCEEDED veya FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Milisaniye cinsinden görev oluşturma zaman damgası.

  • Name
    finished_at
    Type
    timestamp
    Description

    Milisaniye cinsinden tamamlanma zaman damgası. Görevin tamamlanma zamanı yoksa null döner.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bu görev tarafından tüketilen krediler. FAILED görevler için 0 döner (başarısızlık durumunda krediler iade edilir).

  • Name
    api_key_name
    Type
    string
    Description

    Görevi çalıştıran API anahtarının görünen adı. İptal edilmiş anahtarlar için de dolu kalır, böylece anahtar rotasyonundan sonra da geçmiş harcamalar izlenebilir kalır.

  • Name
    api_key_suffix
    Type
    string
    Description

    Aynı ada sahip anahtarları birbirinden ayırt etmek için, bu API anahtarının son dört karakteri.

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