Rölyef API

Tek bir fotoğrafı, 3D baskı, lazer kazıma ve CNC oyma için bir kabartma (bas-relief) 3D modele ve 16-bit derinlik haritasına dönüştürün.

POST/openapi/v1/relief

Bir Rölyef görevi oluştur

Bir Rölyef görevi oluşturur. Bu görev bir fotoğrafı yarım kabartma (bas-relief) modeline dönüştürür. Başarılı olduğunda görev; modeli bir GLB dosyası ve bir STL dosyası, 16 bit gri tonlamalı bir derinlik haritası ve bir önizleme görüntüsü olarak üretir. Yalnızca derinlik haritasını elde etmek için should_generate_model değerini false olarak ayarlayın.

Görev arka planda çalışır.

Bir Rölyef görevi, Yeniden ağ, Dönüştür veya Auto Split gibi başka bir uç noktanın girdisi olamaz. Bu tür istekler 403 döndürür.

Request

POST

/openapi/v1/relief

# Simple request: a low relief, 60 mm on its longer side
curl https://api.meshy.ai/openapi/v1/relief \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# Advanced request: a deep 120 mm relief with a thicker base, curved from side to side
curl https://api.meshy.ai/openapi/v1/relief \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "variant": "high",
    "size_mm": 120,
    "carving_depth_mm": 10,
    "base_thickness_mm": 3,
    "bend_mode": "convex",
    "bend_angle": 90
  }'

Response

{
  "result": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20"
}

Parametreler

Name
image_url
Type
string
Zorunlu
Description
Rölyefe dönüştürülecek fotoğraf; genel erişime açık bir URL veya bir data URI (data:image/png;base64,...) olarak belirtilir.
Görsel; en fazla 20 MB boyutunda, en az 32 × 32 piksel olan bir JPG, JPEG, PNG veya WebP dosyası olmalıdır. Uzun kenarı, kısa kenarının en fazla yaklaşık 16 katı olabilir. Bunların dışındaki herhangi bir görsel 400 döndürür. Meshy, rölyefi oluşturmadan önce saydam alanları siyahla doldurur.
Name
variant
Type
string
varsayılan low
Description
Rölyef stili. Derinlik haritasını şekillendirir ve varsayılan carving_depth_mm değerini belirler.
Kullanılabilir değerler:
- high: 3D baskı parçaları için daha derin oyma.
- low: lazer kazıma, CNC oyma ve ince plaketler için sığ oyma.
null veya "" göndermek, bu parametreyi hiç göndermemekle aynı etkiye sahiptir. Başka herhangi bir değer 400 döndürür.
Name
should_generate_model
Type
boolean
varsayılan true
Description
Rölyef modelinin oluşturulup oluşturulmayacağı. Model ve önizleme görüntüsü olmayan, yalnızca derinlik haritası üreten bir görev için bunu false olarak ayarlayın. Meshy yine de boyut, oyma, taban, bükme ve çözünürlük parametrelerini kontrol eder, ancak bunları kullanmaz. Bu, kredi maliyetini değiştirmez.

Name
size_mm
Type
number
varsayılan 60
Description
Fotoğrafın uzun kenarının model üzerindeki uzunluğu; herhangi bir bükme öncesinde düz halde ölçülür, 20 ile 250 milimetre arasında olabilir. remove_base ile model daha küçük olabilir.
Name
carving_mode
Type
string
varsayılan emboss
Description
Konunun plakadan dışarı mı çıktığı yoksa içine mi oyulduğu.
Kullanılabilir değerler:
- emboss: fotoğrafın yakındaki kısımları dışa doğru çıkıntı yapar.
- engrave: derinlik tersine çevrilir, böylece yakındaki kısımlar içeri doğru kazınır.
Derinlik haritası her iki modda da aynıdır.
Name
carving_depth_mm
Type
number
varsayılan 6 (high), 3 (low)
Description
Rölyefin ne kadar derin oyulacağı, 0 ile 60 milimetre arasında. remove_base değeri true olarak ayarlandığında 0, boş bir model bırakır. Görev yine de başarılı olur ve 20 kredi maliyetine sahiptir; GLB ve STL dosyalarında geometri bulunmaz.

Name
remove_base
Type
boolean
varsayılan false
Description
Arka planın kesilip kesilmeyeceği ve taban plakasının hiç oluşturulmayacağı. true olduğunda, removal_threshold neyin arka plan sayılacağını belirler. Meshy, değeri ne olursa olsun removal_threshold değerini kontrol eder.

Yalnızca şu durumlarda geçerli remove_base = true

Name
removal_threshold
Type
number
varsayılan 0.01
Description
Derinlik haritası 0 ile 1 arasında değiştiğinde, Meshy'nin arka planı kestiği derinlik eşiği, 0.01 ile 1 arasında. Yüksek bir değer, tüm rölyefi keserek boş bir model bırakabilir; bu durum yine de başarılı sayılır ve ücretlendirilir.

Name
base_thickness_mm
Type
number
varsayılan 1, or 0 with remove_base
Description
Taban plakasının kalınlığı, 0.1 ile 10 milimetre arasında. remove_base değeri true olduğunda bu parametreyi boş bırakın veya 0 gönderin.

Name
bend_mode
Type
string
varsayılan off
Description
Rölyefin bükülüp bükülmeyeceği ve hangi yönde bükülmesi gerektiği. off olmadığında, bend_axis ve bend_angle bükümü şekillendirir. Meshy, değerleri ne olursa olsun bunları kontrol eder.
Kullanılabilir değerler:
- off: düz bir rölyef.
- convex: ön yüz dışa doğru kabarır.
- concave: ön yüz içe doğru kavis yapar.

Yalnızca şu durumlarda geçerli bend_mode = convex or concave

Name
bend_axis
Type
string
varsayılan xz
Description
Bükümün hangi kenarları kıvırdığı.
Kullanılabilir değerler:
- xz: sol ve sağ kenarlar.
- yz: üst ve alt kenarlar.
Name
bend_angle
Type
number
varsayılan 60
Description
Bükümün kapsadığı yay, 0 ile 360 derece arasında. 1'in altında rölyef düz kalır.

Name
mesh_resolution
Type
integer
varsayılan 1024
Description
Fotoğrafın uzun kenarı boyunca yer alan ağ noktalarının sayısı, 512 ile 2048 arasında. Daha yüksek bir değer daha ince ayrıntıları korur ve daha büyük dosyalar oluşturur. Varsayılan 1024 değerinde, GLB dosyası yaklaşık 40 ile 50 MB, STL dosyası ise yaklaşık 80 ile 105 MB arasındadır. Kare bir fotoğraf daha büyük boyutlar verir. 2048 değerinde bunlar yaklaşık 150 MB ve 300 MB'dır. Bir büküm bunları daha da büyütür: STL dosyası 2048 değerinde yaklaşık 800 MB'a ulaşabilir.

Dönüş değerleri

result içinde yeni Rölyef görevinin kimliğiyle birlikte 202 Accepted.

Hata modları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Hata mesajı hangi sorunun bulunduğunu belirtir. Örneğin:
- Eksik parametre: image_url gönderilmedi.
- Geçersiz parametre: Bir parametre yanlış türde, kendi aralığının dışında veya kullanılabilir değerlerinden biri değil. Örneğin, variant high ya da low değil, veya mesh_resolution 512 ile 2048 arasında bir tam sayı değil.
- Taban kalınlığı: base_thickness_mm, remove_base değeri true olarak ayarlanmışken 0 değil, ya da remove_base ayarlanmamışken 0.1'in altında.
- Erişilemeyen URL: Meshy, image_url görselini indiremiyor; örneğin URL 404 döndürüyor veya zaman aşımına uğruyor.
- Geçersiz görsel: Görsel; JPG, JPEG, PNG veya WebP dosyası değil, 20 MB'ın üzerinde, 32 × 32 pikselden küçük, çok fazla piksele sahip veya okunamıyor.
- Aşırı en-boy oranı: Görselin uzun kenarı, kısa kenarının yaklaşık 16 katından daha fazla.
İsteği düzeltip tekrar gönderin. Meshy bunun için ücret almaz. Bkz. Hatalar.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Örneğin:
- Yetersiz kredi: Hesapta bu görev için yeterli kredi yok veya hesap bir kredi sınırına ulaştı. Kredi bakiyenizi kontrol edip tekrar deneyin.
- Ücretsiz plan: Görev oluşturmak ücretli bir plan gerektirir. abonelik ayarlarınızdan planınızı yükseltip tekrar deneyin.
Name
403 - Forbidden
Description
İçerik moderasyonu görseli engelledi. Meshy bu istek için ücret almaz. Farklı bir görsel gönderin.
Name
429 - Too Many Requests
Description
Şu sınırlardan biri aşıldı:
- Çok fazla istek gönderdiniz. Bekleyip tekrar deneyin. Bkz. Hız sınırları.
- Görevlerinizden çok fazlası kuyrukta bekliyor veya çalışıyor. Bazılarının tamamlanmasını bekleyip tekrar deneyin.
- Kredisi kalmamış sınırsız bir planda, kredisiz çalışabilecek görev sayısına ulaştınız. Bir görevin tamamlanmasını bekleyin veya kredi ekleyin.

Görev çalışırken bir güvenlik kontrolü görseli reddederse, görev task_error.type değeri invalid_input ve task_error.code değeri provider_content_refused olarak ayarlanmış şekilde başarısız olur. Meshy, görevin kredilerini iade eder. Farklı bir görsel gönderin. Bkz. Hatalar.

GET/openapi/v1/relief/:id

Bir Rölyef görevini al

Belirtilen ID'ye sahip bir Rölyef görevini döndürür.

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev ID'si.

Dönüş Değerleri

Rölyef görev nesnesi.

DELETE/openapi/v1/relief/:id

Bir Rölyef görevini sil

Bir Rölyef görevini, modeli, derinlik haritası ve verileriyle birlikte kalıcı olarak siler. Silme işlemini geri alamazsınız.

Request

DELETE

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Yol parametreleri

Name
id
Type
path
Description
Silinecek görevin ID'si.

Görev durumu

PENDING durumundaki bir görevi silmek, görevi oluştururken kullanılan kredileri iade eder.

IN_PROGRESS durumundaki bir görev silinemez. İstek 409 Conflict döner ve görev çalışmaya devam eder. Meshy, başlamış olan bir görev için iade yapmadığından, bunu silmek hem kredilerinize hem de sonuca mal olur. Görevin SUCCEEDED veya FAILED durumuna ulaşmasını bekleyin, ardından silin.

SUCCEEDED durumundaki bir görevi silmek kredilerini iade etmez. FAILED durumundaki bir görevin kredileri zaten başarısız olduğunda iade edilmiştir.

Dönüş değerleri

Görev silindiğinde 200 OK, görev IN_PROGRESS durumundayken ise 409 Conflict döner.

GET/openapi/v1/relief

Rölyef görevlerini listele

Rölyef görevlerinizin bir listesini döndürür.

Request

GET

/openapi/v1/relief

curl https://api.meshy.ai/openapi/v1/relief?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
    "type": "relief",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
    },
    "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000060000,
    "expires_at": 1700259260000,
    "task_error": null,
    "consumed_credits": 20
  }
]

Parametreler

Name
page_num
Type
integer
Description
Döndürülecek sayfa numarası. 1'den başlar ve varsayılan olarak 1'dir.
Name
page_size
Type
integer
Description
Sayfa başına görev sayısı, en fazla 100. Varsayılan olarak 10'dur. Meshy, 101 ile 255 arasındaki bir değeri 100 olarak kabul eder ve daha büyük bir değer 400 döndürür.
Name
sort_by
Type
string
Description
Sıralama düzeni.
Kullanılabilir değerler:
- +created_at: önce en eski
- -created_at: önce en yeni

Döndürülenler

Sayfalandırılmış bir Rölyef görev nesneleri listesi.

GET/openapi/v1/relief/:id/stream

Bir Rölyef görevini akışla izleme

Bir Rölyef görevinin güncellemelerini Server-Sent Events (SSE) olarak akışla iletir.

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/stream

curl -N https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından gelen görev ID'si.

Döndürülenler

Relief görev nesnelerinin Server-Sent Events olarak akışı.

Her message olayı, Bir Rölyef görevini getir tarafından döndürülenle aynı tam görev nesnesini tutar. Görev PENDING veya IN_PROGRESS durumundayken, olaylar arasında değişen alanlar progress, status, started_at ve preceding_tasks'tır (yalnızca bu görevden önce başka görevler varken bulunur). model_urls, depth_map_url ve thumbnail_url, görev SUCCEEDED durumuna ulaştığında değerlerini alır. Yalnızca derinlik haritası üreten bir görev, model_urls alanını {} olarak ve thumbnail_url alanını boş olarak tutar.

Bir error olayı yalnızca status_code ve message içerir, bu yüzden status okumadan önce olay adını kontrol edin.

Rölyef görev nesnesi

Bir Rölyef görev nesnesi, bir fotoğraftan yapılan bir rölyefi tanımlar. model_urls, depth_map_url ve thumbnail_url her zaman mevcuttur ve görev başarılı olana kadar boştur.

The Relief Task Object

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Depth map only

{
  "id": "0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31",
  "type": "relief",
  "model_urls": {},
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31/output/depth.png?Expires=***",
  "thumbnail_url": "",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1700259230000,
  "task_error": null,
  "consumed_credits": 20
}

Name
id
Type
string
Description
Görev kimliği. Bunu opak bir dize olarak ele alın ve biçimine güvenmeyin.
Name
type
Type
string
Description
Görev türü, her zaman relief.
Name
model_urls
Type
object
Description
Rölyef modeli için indirme URL'leri. Dosyalar büyük olabilir; mesh_resolution tipik boyutları listeler.
- Name
  glb
  Type
  string
  Description
  Dokusuz GLB dosyası. Birimleri metredir. Yalnızca derinlik haritası olan bir görev için mevcut değildir.
- Name
  stl
  Type
  string
  Description
  Aynı model, ikili bir STL dosyası olarak. Birimleri milimetredir, bu yüzden rölyefin gerçek boyutunda, Z yukarı bakacak şekilde açılır. Yalnızca derinlik haritası olan bir görev için mevcut değildir.
Name
depth_map_url
Type
string
Description
Rölyefin oluşturulduğu 16 bit gri tonlamalı derinlik haritası için indirme URL'si. Daha parlak pikseller daha yüksektir. Değerler milimetre değil, göreli yüksekliklerdir. Lazer gravür ve CNC yazılımları bunu bir yükseklik haritası olarak kullanabilir. Dosya yaklaşık 1 ila 2 MB'dır. Eğer yoksa boştur.
Name
thumbnail_url
Type
string
Description
Rölyef modelinin önizleme görüntüsü için indirme URL'si. Yalnızca derinlik haritası olan bir görev de dahil olmak üzere, hiçbir şey oluşturulmadıysa boştur.
Name
progress
Type
integer
Description
Görevin yüzde olarak ne kadarının tamamlandığı. Görev başlayana kadar 0, başarılı olduğunda 100'dür.
Name
status
Type
string
Description
Görev durumu, PENDING, IN_PROGRESS, SUCCEEDED veya FAILED değerlerinden biri.
Name
preceding_tasks
Type
integer
Description
Kuyrukta bu görevden önce gelen görev sayısı. Değer 0 olduğunda bu alan dışarıda bırakılır, dolayısıyla yalnızca önünde görevler varken görünür.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman, Unix milisaniye cinsinden.
Name
started_at
Type
timestamp
Description
Görevin başladığı zaman, Unix milisaniye cinsinden. Görev başlayana kadar 0'dır.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman, Unix milisaniye cinsinden. Görev tamamlanana kadar 0'dır.
Name
expires_at
Type
timestamp
Description
Görevin sonucunun sona erdiği zaman, Unix milisaniye cinsinden. Görev tamamlanana kadar 0'dır.
Name
task_error
Type
object
Description
Görev başarısız olduğunda hata ayrıntıları. Bkz. Hatalar.
Name
consumed_credits
Type
integer
Description
Görevin kullandığı kredi sayısı: 20, veya Meshy'nin iade ettiği FAILED bir görev için 0.