Yeniden Ağ API'si

Yeniden Ağ API'si, diğer Meshy API'leri (Görselden 3D'ye veya Metinden 3D'ye gibi) tarafından oluşturulan mevcut 3D modelleri yeniden ağ yapısına dönüştürmenize ve çeşitli formatlara aktarmanıza olanak tanır. Bu bölüm, Yeniden Ağ API'sinin nasıl kullanılacağına dair ayrıntılar sunar.

POST/openapi/v1/remesh

Yeniden Ağ Görevi Oluştur

Bu uç nokta yeni bir yeniden ağ görevi oluşturur.

Görev arka planda çalışır. Genellikle ne kadar sürdüğünü görmek için İşlem Süreleri sayfasına bakın.

Format dönüştürme ve yeniden boyutlandırma için özel Dönüştür API ve Yeniden Boyutlandır API kullanın. Aşağıdaki kullanımdan kaldırılmış parametreler çalışmaya devam edecek, ancak yeni entegrasyonlar için yeni uç noktaları öneriyoruz.

Parametreler

input_task_id veya model_url değerlerinden yalnızca biri zorunludur. Her ikisi de sağlanırsa, input_task_id önceliklidir.

Name
input_task_id
Type
string
Zorunlu
Description
Yeniden ağ oluşturmak istediğiniz tamamlanmış Görselden 3D'ye veya Metinden 3D'ye görevinin kimliği. Bu görev şu görevlerden biri olmalıdır: Metinden 3D'ye Preview, Metinden 3D'ye Refine, Görselden 3D'ye veya Yeniden dokulama. Ayrıca durumu SUCCEEDED olmalıdır.

Name
model_url
Type
string
Zorunlu
Description
Lütfen Meshy'nin yeniden ağ oluşturması için herkese açık bir URL veya data URI aracılığıyla bir 3D model sağlayın. Desteklenen formatlar: .glb, .gltf, .obj, .fbx, .stl.
Data URI'ler için MIME type olarak şunu kullanın: application/octet-stream.
Maksimum dosya boyutu: Bir http veya https URL'si için 400 MB, bir data: URI'si için 100 MB.
100 MB'den büyük bir GLB, glTF, FBX veya OBJ dosyası en fazla 10.000.000 yüzeye sahip olabilir. Yüzeyler üçgen olarak sayılır: bir dörtgen 2 olarak sayılır ve birden fazla kez çizilen bir ağ, kopya başına bir kez sayılır. 100 MB'nin üzerinde, bir FBX dosyası ikili FBX 7.1 veya daha yeni olmalı ve bir GLB veya glTF dosyası Draco sıkıştırması kullanmamalıdır.

Name
target_formats
Type
string[]
varsayılan ["glb"]
Description
Yeniden ağ oluşturulan model için hedef formatların listesi. Belirtilmezse yalnızca GLB oluşturulur.
Kullanılabilir değerler: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
varsayılan triangle
Description
Oluşturulan modelin topology'sini belirtin.
Kullanılabilir değerler:
- quad: Dörtgen ağırlıklı bir ağ oluştur.
- triangle: Küçültülmüş bir üçgen ağ oluştur.
Name
target_polycount
Type
integer
varsayılan 30,000
Description
Oluşturulan modeldeki hedef poligon sayısını belirtin. Gerçek poligon sayısı, geometrinin karmaşıklığına bağlı olarak hedeften sapabilir.
Geçerli aralık 100 ile 300.000 (dahil) arasındadır.
Name
decimation_mode
Type
integer
Description
Bir poligon sayısı seviyesi belirleyerek uyarlanabilir küçültmeyi etkinleştirin. Bu ayarlandığında target_polycount göz ardı edilir.
Kullanılabilir değerler:
- 1: Uyarlanabilir — ultra poligon sayısı.
- 2: Uyarlanabilir — yüksek poligon sayısı.
- 3: Uyarlanabilir — orta poligon sayısı.
- 4: Uyarlanabilir — düşük poligon sayısı.
Name
resize_height
Type
number
⚠ kullanımdan kaldırıldı
varsayılan 0
Description
Modeli metre cinsinden belirli bir yüksekliğe yeniden boyutlandırın. Bunun yerine özel Yeniden Boyutlandır API kullanmanızı öneririz.
auto_size, resize_height ve resize_longest_side birbirini dışlar.
Name
resize_longest_side
Type
number
⚠ kullanımdan kaldırıldı
varsayılan 0
Description
Modeli, sınırlayıcı kutunun en uzun boyutu metre cinsinden belirtilen değere eşit olacak şekilde yeniden boyutlandırın. Bunun yerine özel Yeniden Boyutlandır API kullanmanızı öneririz.
auto_size, resize_height ve resize_longest_side birbirini dışlar.
Name
auto_size
Type
boolean
⚠ kullanımdan kaldırıldı
varsayılan false
Description
true olarak ayarlandığında, servis nesnenin gerçek dünyadaki yüksekliğini otomatik olarak tahmin etmek ve modeli buna göre yeniden boyutlandırmak için AI görüntü işlemeyi kullanır. Bunun yerine özel Yeniden Boyutlandır API kullanmanızı öneririz.
auto_size, resize_height ve resize_longest_side birbirini dışlar.

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

Name
origin_at
Type
string
⚠ kullanımdan kaldırıldı
varsayılan bottom
Description
Orijinin konumu. Bunun yerine özel Yeniden Boyutlandır API kullanmanızı öneririz.
Kullanılabilir değerler: bottom, center.

Name
convert_format_only
Type
boolean
⚠ kullanımdan kaldırıldı
Description
true ise, servis yalnızca girdi model dosyasının formatını değiştirir ve topology, resize_height ve target_polycount gibi diğer girdileri göz ardı eder. Bunun yerine özel Dönüştür API kullanmanızı öneririz.
convert_format_only true olarak ayarlanmışsa target_formats sağlanmalıdır.

Name
alpha_thumbnail
Type
boolean
varsayılan false
Description
true olarak ayarlandığında, görev ek olarak önizlemenin şeffaf arka planlı (RGBA) bir sürümünü oluşturur ve bunu GET yanıtında alpha_thumbnail_url olarak döndürür. Mevcut thumbnail_url alanı değişmez.

Döndürülenler

Yanıtın result özelliği, yeni oluşturulan yeniden ağ görevinin id değerini içerir.

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemedi. Yaygın nedenler:
- Eksik parametre: model_url veya input_task_id sağlanmalıdır.
- Geçersiz girdi görevi: input_task_id, desteklenen bir modelden gelen başarılı bir göreve işaret etmelidir.
- Geçersiz model formatı: model_url desteklenmeyen bir uzantıya sahip bir dosyaya işaret ediyor.
- Erişilemeyen URL: model_url indirilemedi.
- Model dosyası çok büyük: model_url dosyası 400 MB'yi (http veya https URL'si) veya 100 MB'yi (data: URI'si) aşıyor.
- Çok fazla yüzey: model_url dosyası 100 MB'den büyük ve 10.000.000'den fazla yüzeye sahip. Yüzey sayısını azaltın, ardından dosyayı tekrar gönderin.
- 100 MB üzerinde ASCII FBX: model_url dosyası 100 MB'nin üzerinde bir ASCII FBX. Bunu ikili FBX veya GLB olarak gönderin.
- Okunamayan model dosyası: model_url dosyası 100 MB'nin üzerinde ve başlığı okunamıyor, örneğin Draco sıkıştırmalı bir GLB veya glTF ya da 7.1'den eski ikili bir FBX.
- Model başlığı çok karmaşık: model_url dosyası 100 MB'nin üzerinde ve başlığında kontrol edilecek çok fazla ağ, düğüm veya kayıt var. Dosyadaki nesne sayısını azaltın, ardından tekrar gönderin.
- Geçersiz topology: topology parametresi geçersiz.
- Birbirini dışlayan parametreler: auto_size ve resize_height aynı anda ayarlanamaz.
Name
401 - Unauthorized
Description
Kimlik doğrulama başarısız oldu. Lütfen API anahtarınızı kontrol edin.
Name
402 - Payment Required
Description
Bu görevi gerçekleştirmek için yetersiz kredi.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

Request

POST

/openapi/v1/remesh

# Basic remesh with custom formats and resize
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

# Quad remesh with auto-size
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "auto_size": true
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/remesh/:id

Bir Yeniden Ağ Görevini Getir

Bu uç nokta, bir yeniden ağ görevini ID'sine göre getirir.

Parametreler

Name
id
Type
path
Description
Getirilecek yeniden ağ görevinin ID'si.

Dönüş Değeri

Yeniden Ağ Görevi nesnesi.

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

DELETE/openapi/v1/remesh/:id

Bir Yeniden Ağ Görevini Sil

Bu uç nokta, bir yeniden ağ görevini ilişkili tüm modeller ve verilerle birlikte kalıcı olarak siler. Bu işlem geri alınamaz.

Yol Parametreleri

Name
id
Type
path
Description
Silinecek yeniden ağ görevinin ID'si.

Görev Durumu

Hâlâ PENDING durumunda olan bir görev silinir ve oluşturma sırasında harcanan kredi iade edilir.

Zaten IN_PROGRESS durumunda olan bir görev silinemez: istek 409 Conflict ile reddedilir ve görev çalışmaya devam eder. Worker'ın zaten başlatmış olduğu bir görev için krediler iade edilemez, bu yüzden çalışma sırasında silmek hem kredilerinize hem de sonuca mal olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Sonlanmış bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görev iade yapılmadan silinir.

Dönüş Değerleri

Başarılı olduğunda 200 OK, görev IN_PROGRESS durumundayken 409 Conflict döner.

Request

DELETE

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -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 is left 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."
}

GET/openapi/v1/remesh

Yeniden Ağ Görevlerini Listele

Bu uç nokta, Yeniden ağ görevlerinin bir listesini almanızı sağlar.

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
Description
Sıralama yapı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.

Döndürülenler

Yeniden Ağ Görevi Nesneleri'nin sayfalanmış bir listesini döndürür.

Request

GET

/openapi/v1/remesh

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]

GET/openapi/v1/remesh/:id/stream

Bir Yeniden Ağ Görevini Akışla Aktar

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir Yeniden Ağ görevi için gerçek zamanlı güncellemeleri akışla aktarır.

Parametreler

Name
id
Type
path
Description
Akışla aktarılacak Yeniden Ağ görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Yeniden Ağ Görevi Nesnelerinin Server-Sent Events olarak bir akışını döndürür.

PENDING veya IN_PROGRESS durumundaki görevler için yanıt akışı yalnızca gerekli progress ve status alanlarını içerecektir.

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

Remesh Görevi Nesnesi

Remesh Görevi nesnesi, Meshy'nin mevcut bir 3D modeli yeniden ağlamak (remesh) ve çeşitli formatlara dışa aktarmak için kullandığı bir iş birimini temsil eder. Nesne aşağıdaki özelliklere sahiptir:

Özellikler

Name
id
Type
string
Description
Görev için benzersiz tanımlayıcı. Uygulama detayı olarak görev id'leri için k-sıralanabilir bir UUID kullansak da, id'nin formatı hakkında herhangi bir varsayımda bulunmamalısınız.
Name
type
Type
string
Description
Remesh görevinin türü. Değer remesh şeklindedir.
Name
model_urls
Type
object
Description
Meshy tarafından oluşturulan dokulu 3D model dosyasına indirilebilir URL. Bir format oluşturulmamışsa, boş bir string döndürmek yerine o formata ait özellik atlanır.
- Name
  glb
  Type
  string
  Description
  GLB dosyasına indirilebilir URL.
- Name
  fbx
  Type
  string
  Description
  FBX dosyasına indirilebilir URL.
- Name
  obj
  Type
  string
  Description
  OBJ dosyasına indirilebilir URL.
- Name
  usdz
  Type
  string
  Description
  USDZ dosyasına indirilebilir URL.
- Name
  blend
  Type
  string
  Description
  Blender dosyasına indirilebilir URL.
- Name
  stl
  Type
  string
  Description
  STL dosyasına indirilebilir URL.
- Name
  3mf
  Type
  string
  Description
  3MF dosyasına indirilebilir URL. Yalnızca target_formats üzerinden 3mf talep edildiğinde bulunur.
Name
thumbnail_url
Type
string
Description
Yeniden ağlanmış (remesh) modelden render edilen bir önizleme görüntüsüne indirilebilir URL.
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url değerinin şeffaf arka planlı (RGBA) sürümüne indirilebilir URL. Yalnızca görev alpha_thumbnail: true ile oluşturulduğunda ve şeffaf önizleme başarıyla render edildiğinde bulunur; aksi takdirde bu alan atlanır.
Name
progress
Type
integer
Description
Görevin ilerlemesi (progress). Görev henüz başlamadıysa, bu özellik 0 olur. Görev başarıyla tamamlandığında bu değer 100 olur.
Name
status
Type
string
Description
Görevin durumu. Olası değerler PENDING, IN_PROGRESS, SUCCEEDED, FAILED değerlerinden biridir.
Name
preceding_tasks
Type
integer
Description
Öncesindeki görevlerin sayısı.
Bu alanın değeri yalnızca görev durumu PENDING olduğunda anlamlıdır.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman damgası, milisaniye cinsinden.
Name
started_at
Type
timestamp
Description
Görevin başladığı zaman damgası, milisaniye cinsinden. Görev henüz başlamadıysa, bu özellik 0 olur.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman damgası, milisaniye cinsinden. Görev henüz tamamlanmadıysa, bu özellik 0 olur.
Name
task_error
Type
object
Description
Başarısız görevler için hata detayları. Tam task_error nesne referansı için Hatalar bölümüne bakın.
Name
consumed_credits
Type
integer
Description
Bu görev tarafından tüketilen kredi sayısı. Görev durumu PENDING, IN_PROGRESS veya SUCCEEDED olduğunda bulunur. FAILED görevler için 0 döner (başarısızlık durumunda krediler iade edilir).

Example Remesh Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}