Dönüştür API

Bir 3D modeli, bir Meshy görevinden veya bir model dosyasından diğer dosya formatlarına dönüştürün.

POST/openapi/v1/convert

Dönüştürme görevi oluştur

Bir Dönüştürme görevi oluşturur. Görev arka planda çalışır. Bir görevin genellikle ne kadar sürdüğü hakkında bilgi için bkz. İşlem süreleri.

Request

POST

/openapi/v1/convert

curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

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

Parametreler

Name
input_task_id
Type
string
Zorunlu
Description
model_url gönderilmediği sürece gereklidir. Örneğin bir Metinden 3D'ye, Görselden 3D'ye, Yeniden ağ, Yeniden boyutlandır veya Yeniden dokulama görevi gibi, bir 3D model üreten görevin ID'si. Görev API'den gelmeli ve SUCCEEDED durumunda olmalıdır.

Name
model_url
Type
string
Zorunlu
Description
input_task_id gönderilmediği sürece gereklidir. Dönüştürülecek model; herkese açık bir URL veya bir data URI olarak verilir. İkisi de gönderilirse Meshy input_task_id değerini kullanır.
Model, http veya https URL'sinden en fazla 400 MB, ya da data URI olarak en fazla 100 MB boyutunda bir GLB, glTF, OBJ, FBX veya STL dosyası olmalıdır. Data URI için application/octet-stream MIME type'ını kullanın.
100 MB'den büyük bir dosya ayrıca şu kurallara da uymalıdır:
- Bir GLB, glTF, FBX veya OBJ dosyası en fazla 10.000.000 yüze sahip olabilir. Meshy yüzleri üçgen olarak sayar; bu nedenle bir dörtgen 2 olarak sayılır ve birden fazla kez çizilen bir ağ her kopya için bir kez sayılır.
- Bir FBX dosyası, ikili (binary) FBX 7.1 veya daha yeni bir sürüm olmalıdır.
- Bir GLB veya glTF dosyası Draco sıkıştırması kullanmamalıdır.

Name
target_formats
Type
string[]
Zorunlu
Description
Oluşturulacak dosya biçimleri. En az bir tane listeleyin. Eksik veya boş bir liste 400 döndürür.
Kullanılabilir değerler:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Dönüş değerleri

Yanıtın result alanı, yeni Dönüştürme görevinin ID'sini tutar.

Hata modları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Hata mesajı hangi sorunun bulunduğunu belirtir. Örneğin:
- Eksik parametre: Ne model_url ne de input_task_id gönderilmedi.
- Eksik target_formats: target_formats eksik veya hiçbir biçim listelemiyor.
- Geçersiz girdi görevi: input_task_id, bir model dosyası içeren başarılı bir API görevi değil.
- Geçersiz model biçimi: model_url dosyasının uzantısı desteklenmiyor.
- Ulaşılamayan URL: Meshy, model_url dosyasını indiremiyor.
- Model dosyası çok büyük: model_url dosyası, http veya https URL'sinden 400 MB'den, ya da data URI olarak 100 MB'den büyük.
- Çok fazla yüz: model_url dosyası 100 MB'den büyük ve 10.000.000'den fazla yüze sahip. Yüz sayısını azaltıp dosyayı tekrar gönderin.
- 100 MB'den büyük ASCII FBX: model_url dosyası, 100 MB'den büyük bir ASCII FBX. Bunu ikili (binary) FBX veya GLB olarak gönderin.
- Okunamayan model dosyası: model_url dosyası 100 MB'den büyük ve Meshy başlığını okuyamıyor. Örneğin, Draco sıkıştırmalı bir GLB veya glTF ya da 7.1'den eski bir ikili FBX olabilir.
- Model başlığı çok karmaşık: model_url dosyası 100 MB'den büyük ve başlığı, kontrol edilemeyecek kadar çok ağ, düğüm veya kayıt içeriyor. Dosyadaki nesne sayısını azaltıp tekrar gönderin.
İsteği düzeltip tekrar gönderin. 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, ya da hesap bir kredi sınırına ulaştı. Kredi bakiyenizi kontrol edip tekrar deneyin.
- Ücretsiz plan: Görev oluşturmak için ücretli bir plan gereklidir. abonelik ayarlarınızdan planınızı yükseltip tekrar deneyin.
Name
403 - Forbidden
Description
input_task_id, bu uç noktanın dönüştüremediği bir kabartma (bas-relief) modeli. Mesaj şudur: This model type does not support this operation. Farklı bir model gönderin.
Name
404 - Not Found
Description
input_task_id, görevlerinizden hiçbiriyle eşleşmiyor. Görev ID'sini kontrol edip isteği tekrar gönderin.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız. Bekleyip tekrar deneyin. Bkz. Hız sınırları.

GET/openapi/v1/convert/:id

Convert görevi al

Bir Convert görevini kimliğine göre döndürür.

Request

GET

/openapi/v1/convert/:id

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev kimliği.

Dönüş Değerleri

Convert görev nesnesi.

DELETE/openapi/v1/convert/:id

Bir Convert görevini sil

Bir Convert görevini, modelleri ve verileri dahil olmak üzere kalıcı olarak siler. Bir silme işlemini geri alamazsınız.

Request

DELETE

/openapi/v1/convert/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/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 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 kimliği.

Görev durumu

PENDING durumundaki bir görevi silmek, oluşturulurken 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ış bir görevin kredilerini iade etmez, bu yüzden onu silmek hem kredilerinizi hem de sonucu kaybetmenize neden olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Son bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görevi silmek kredilerini iade etmez.

Dönüş değerleri

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

GET/openapi/v1/convert

Dönüştürme görevlerini listele

Dönüştürme görevlerinizin bir listesini döndürür.

Request

GET

/openapi/v1/convert

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

Parametreler

Name
page_num
Type
integer
varsayılan 1
Description
Döndürülecek sayfa numarası, en fazla 255. Daha büyük bir değer 400 döndürür.

Name
page_size
Type
integer
varsayılan 10
Description
Sayfa başına görev sayısı, en fazla 100.

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

Convert görev nesnelerinin sayfalandırılmış bir listesi.

GET/openapi/v1/convert/:id/stream

Dönüştürme görevini akışla izleyin

Bir Dönüştürme görevinin güncellemelerini Server-Sent Events (SSE) olarak akışla iletir.

Request

GET

/openapi/v1/convert/:id/stream

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

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

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

Parametreler

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

Dönüş Değerleri

Dönüştürme görevi nesnelerinin Server-Sent Events olarak akışı.

Her olay, Get uç noktasının döndürdüğü ile aynı biçimde, görev nesnesinin tamamını içerir. Görev PENDING veya IN_PROGRESS durumundayken, sonuç alanlarının henüz değeri yoktur.

Convert görevi nesnesi

Bir Convert görevi nesnesi, bir 3D modelin bir format dönüşümünü tanımlar. Görev başarılı olduğunda durumu, progress'i ve model dosyalarını tutar.

Özellikler

Name
id
Type
string
Description
Görev ID'si. Bunu opak bir dize olarak kabul edin ve biçimine güvenmeyin.
Name
type
Type
string
Description
Görev türü, her zaman convert.
Name
model_urls
Type
object
Description
Dönüştürülen model için indirme URL'leri, her dosya biçimi için bir tane. Yalnızca target_formats içindeki biçimlerin URL'leri vardır. İstemediğiniz bir biçimin anahtarı yoktur, boş bir dize de değildir.
Name
progress
Type
integer
Description
Görevin ne kadarının tamamlandığı, yüzde olarak. Görev başlayana kadar 0, başarılı olduğunda 100 değerindedir.
Name
status
Type
string
Description
Görev durumu, PENDING, IN_PROGRESS, SUCCEEDED, FAILED veya CANCELED değerlerinden biri.
Name
preceding_tasks
Type
integer
Description
Kuyrukta bu görevden önce gelen görev sayısı. Bu değer yalnızca görev PENDING durumundayken anlamlıdı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 değerindedir.
Name
finished_at
Type
timestamp
Description
Görevin bittiği zaman, Unix milisaniye cinsinden. Görev bitene kadar 0 değerindedir.
Name
expires_at
Type
timestamp
Description
Görevin indirme URL'lerinin sona erdiği zaman, Unix milisaniye cinsinden. Görev bitene kadar 0 değerindedir.
Name
texture_urls
Type
array
Description
Görev başarılı olduğunda, modelin doku haritaları için indirme URL'leri: her doku seti için bir tane olmak üzere nesnelerden oluşan bir dizi. Her nesnenin bir base_color URL'si vardır ve ayrıca metallic, roughness, normal, emission ve metallic_roughness URL'lerine sahip olabilir. Görev başarılı olana kadar null değerindedir ve modelin doku haritası yoksa boş bir dizidir.
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ı, bir Convert görevi için 1 değerindedir. FAILED bir görev için 0 değerindedir.