Kullanım API'si

Faturalandırma dışa aktarımları ve maliyet raporları için ekibinizin tamamlanmış API görevlerini ve her birinin kullandığı kredileri listeleyin.

Bu uç noktayı çağırmak için bir Studio veya Enterprise ekibinin aktif bir üyesine ait bir API anahtarı kullanın. Yalnızca sahipler ve yöneticiler değil, herhangi bir üye bu uç noktayı çağırabilir. Başka herhangi bir API anahtarıyla istek 403 döner.

GET/openapi/v1/usage/tasks

Kullanım kayıtlarını listele

Ekibinizin kullanım kayıtlarının bir sayfasını, varsayılan olarak en yeniden en eskiye doğru sıralanmış şekilde döndürür. start_time ve end_time belirtilmezse kayıtlar son 30 günü kapsar. Bu uç noktayı çağırmak ücretsizdir.

Kayıtlar şu görevleri içerir:

SUCCEEDED veya FAILED olarak tamamlanan API görevleri
Ekibin mevcut her üyesinin, herhangi bir API anahtarından gelen görevleri
Sildiğiniz görevler ve dosyaları süresi dolmuş görevler

Kayıtlar şu görevleri içermez:

Hâlâ PENDING veya IN_PROGRESS durumundaki görevler ve CANCELED görevler
Ekipten ayrılmış kişilerin görevleri
Creative Lab görevleri
Meshy'nin yapay zeka ajanlarının çalıştırdığı görevler
Meshy web uygulamasında yapılan işler

Bir görev, kayıtlarda yalnızca tamamlandıktan sonra, created_at zaman aralığında görünür. Meshy, bir görevi oluştururken kredi tahsil eder, bu nedenle hâlâ çalışmakta olan bir görev kayıtlarda bulunmaz. Kayıtları kredi bakiyenizle karşılaştırmadan önce son zaman aralıklarını tekrar çekin veya kısa bir gecikmeden sonra dışa aktarın.

Ekibinizin bir veri saklama süresi varsa, zaman aralığı bu sürenin izin verdiğinden daha erken başlamaz.

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": {}
  }
]

Parametreler

Name
page_num
Type
integer
varsayılan 1
Description
1 ile 255 arasında döndürülecek sayfa. 255'in üzerindeki bir değer 400 döner. Bir zaman aralığı en fazla 255 sayfa tutar, bu nedenle büyük bir dışa aktarımı daha kısa zaman aralıklarına bölün.
Name
page_size
Type
integer
varsayılan 10
Description
Sayfa başına kayıt sayısı, 1 ile 100 arasında. 101 ile 255 arasındaki bir değer 100 kayıt döndürür, 255'in üzerindeki bir değer ise 400 döner.
Name
sort_by
Type
string
varsayılan -created_at
Description
Sıralama düzeni.
Kullanılabilir değerler:
- +created_at: önce en eski
- -created_at: önce en yeni
Bir URL içinde + işaretini %2B olarak yazın. Aksi hâlde + bir boşluk olarak okunur ve istek 400 döner.
Name
start_time
Type
string
Description
Zaman aralığının başlangıcı, RFC 3339 zaman damgası olarak, örneğin 2026-08-01T00:00:00Z. Kayıtlar, bu zamanda veya sonrasında oluşturulan görevleri içerir. Zaman aralığını end_time'dan 30 gün önce başlatmak için boş bırakın.
Zaman aralığı en fazla 366 gün sürebilir. Daha uzun bir aralık 400 döner, bu nedenle daha uzun bir dışa aktarımı birkaç aralığa bölün.
Name
end_time
Type
string
Description
Zaman aralığının sonu, RFC 3339 zaman damgası olarak. Kayıtlar, bu zamandan önce oluşturulan görevleri içerir. İsteğinizin yapıldığı zamanda bitirmek için boş bırakın.
Name
endpoints
Type
string
Description
Dahil edilecek uç noktaların, endpoint alanıyla aynı adlarla virgülle ayrılmış bir listesi. Her uç noktayı dahil etmek için boş bırakın. Bilinmeyen bir ad 400 döner.
Kullanılabilir değerler:
- text-to-3d: preview ve refine dahil her Metinden 3D'ye görevi
- text-to-3d-preview: yalnızca preview görevleri
- text-to-3d-refine: yalnızca refine görevleri
- 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
Name
status
Type
string
Description
Dahil edilecek durum, SUCCEEDED veya FAILED. Her ikisini de dahil etmek için boş bırakın. Başka herhangi bir değer 400 döner.

Döndürülenler

Kullanım kayıtlarından oluşan bir dizi döndürür. Eşleşen kayıt olmadığında dizi boş olur.

Hata modları

Name
400 - Bad Request
Description
Bir parametre geçersizdir ve hata mesajı hangisi olduğunu belirtir. Parametreyi düzeltin, ardından isteği tekrar gönderin.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
403 - Forbidden
Description
API anahtarının hesabı, bir Studio veya Enterprise ekibinin aktif bir üyesi değil. Mesaj This endpoint is available on Studio and Enterprise plans şeklindedir. Bir Studio veya Enterprise ekip üyesine ait bir API anahtarı kullanın.
Name
429 - Too Many Requests
Description
Çok fazla istek gönderdiniz. Retry-After içindeki saniye kadar bekleyin, ardından tekrar deneyin.

Kullanım kaydı nesnesi

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
Görev kimliği, oluşturan uç noktanın döndürdüğü kimlikle aynıdır. Görevin kendisini, çıktı URL'leriyle birlikte almak için bu kimliği ilgili uç noktanın get rotasına gönderin, örneğin bir image-to-3d kaydı için GET /openapi/v1/image-to-3d/{task_id}.
Name
endpoint
Type
string
Description
Görevin çalıştığı uç nokta, örneğin image-to-3d veya rig. Bir Metinden 3D'ye görevi kendi aşamasını gösterir, text-to-3d-preview veya text-to-3d-refine.
Daha eski kayıtlar, endpoints filtresinin kabul etmediği, kullanımdan kaldırılmış uç nokta adlarına sahip olabilir.
Name
status
Type
string
Description
Görevin nihai durumu, SUCCEEDED veya FAILED.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman, Unix milisaniye cinsinden.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman, Unix milisaniye cinsinden. Görevin bitiş zamanı yoksa null.
Name
consumed_credits
Type
integer
Description
Görevin kullandığı kredi sayısı, iadelerden sonraki hâliyle. Başarısız bir görev için 0, çünkü Meshy bunu iade eder; ayrıca Basılabilirliği analiz et gibi ücretsiz bir görev için de 0.
Name
api_key_name
Type
string
Description
Görevi çalıştıran API anahtarının adı. Bir uygulama girişiyle çalıştırılan bir görev için bu, uygulamanın adıdır, örneğin Meshy CLI.
Bazı durumlarda boş bir dizedir, örneğin:
- Görev hiç ücretlendirilmedi, örneğin ücretsiz olan bir Basılabilirliği analiz et görevi.
- API anahtarı silinmiş.
- API anahtarı son birkaç dakika içinde oluşturulmuş.
Name
api_key_suffix
Type
string
Description
Aynı ada sahip anahtarları birbirinden ayırmak için o API anahtarının son dört karakteri. api_key_name boş olduğunda ve Meshy CLI gibi uygulama girişleri için boş bir dizedir.
Name
metadata
Type
object
Description
Görev oluşturulduğunda X-Meshy-Metadata başlığında gönderilen etiketler. Hiçbiri yoksa {}. Bkz. Metadata.