Kullanım API'si

Kullanım API'si, 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 plandaki veya ekibi olmayan anahtarlar 403 yanıtı alır.

GET/openapi/v1/usage/tasks

Kullanım Kayıtlarını Listele

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 (örn. 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ıklar arasında sayfalayın.

  • Name
    end_time
    Type
    string
    Description

    created_at aralığının bitişi, 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, print-split — burada text-to-3d, hem preview hem de refine 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

Kullanım Kaydı 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 edilir, bu nedenle siz dışa aktarma yaparken 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 zamandaki 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"
  }
]

Kullanım Kaydı Nesnesi

  • 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 (her okumada yeniden imzalanan çıktı modeli veya görsel URL'leri dahil) almak için, bunu ilgili alma uç noktasına iletin, örn. GET /openapi/v1/{endpoint}/{task_id}.

  • Name
    endpoint
    Type
    string
    Description

    Görevin çalıştığı uç nokta, örn. image-to-3d veya text-to-3d-refine. Metinden 3D'ye görevleri, aşamalarını (text-to-3d-preview / text-to-3d-refine) bildirir.

  • Name
    status
    Type
    string
    Description

    Nihai görev durumu: SUCCEEDED veya FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

    Görevin oluşturulma zaman damgası, milisaniye cinsinden.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tamamlanma zaman damgası, milisaniye cinsinden. Görevin bir tamamlanma zamanı yoksa null.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bu görev tarafından tüketilen krediler. FAILED görevler için 0 döndürür (hata 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 geçmiş harcamalar izlenebilir olarak kalır.

  • Name
    api_key_suffix
    Type
    string
    Description

    Aynı ada sahip anahtarları birbirinden ayırt etmek için o 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"
}