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 arasında sayfalar arasında gezinerek toplu dışa aktarım yapın.

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örevlerinden bir sayfayı, en yeniden en eskiye doğru döndürür. Belirtilen bir zaman aralığı olmadan 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 değer 100 öğedir.

  • Name
    sort_by
    Type
    string
    varsayılan -created_at
    Description

    Sıralama için kullanılacak alan.

    Kullanılabilir değerler:

    • +created_at: Oluşturulma zamanına göre artan sırayla sırala.
    • -created_at: Oluşturulma zamanına göre azalan sırayla 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 aktarımlar için ardışık aralıklar arasında 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 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 dışa aktarım yaptığınızda hâlâ çalışmakta olan bir görev, o aralığın sonuçlarında henüz 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ı olan 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 kimliği — oluşturan uç noktanın döndürdüğü aynı kimlik. Görevin kendisini (her okumada yeniden imzalanan çıktı model 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. Text to 3D görevleri kendi 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 olur.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bu görev tarafından tüketilen krediler. FAILED görevler için 0 döndürür (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 edilen anahtarlar için de doldurulmuş kalır, böylece anahtar rotasyonundan sonra bile geçmiş harcamalar izlenebilir kalır.

  • Name
    api_key_suffix
    Type
    string
    Description

    O API anahtarının son dört karakteri, aynı ada sahip anahtarları birbirinden ayırt etmek için kullanılır.

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