Teks ke 3D API

Teks ke 3D API adalah fitur yang memungkinkan Anda mengintegrasikan kemampuan Teks ke 3D dari Meshy ke dalam aplikasi Anda sendiri. Di bagian ini, Anda akan menemukan semua informasi yang Anda butuhkan untuk memulai dengan API ini.

Teks ke 3D menggunakan alur kerja dua langkah. Pertama, buat tugas preview (mode: "preview") untuk menghasilkan mesh 3D tanpa tekstur, sehingga Anda dapat mengevaluasi bentuknya. Kemudian, teruskan ID tugas preview yang telah selesai ke tugas refine (mode: "refine") untuk menerapkan tekstur pada mesh tersebut. Kedua langkah ini menggunakan endpoint yang sama.

POST/openapi/v2/text-to-3d

Create a Text to 3D Preview Task

Endpoint ini membuat tugas preview Teks ke 3D, yang menghasilkan mesh 3D tanpa tekstur (hanya geometri) dari sebuah prompt teks. Ini adalah langkah pertama dari alur kerja dua langkah. Setelah preview berhasil, gunakan ID tugas yang dikembalikan untuk membuat tugas refine untuk pemberian tekstur. Lihat The Text to 3D Task Object untuk skema respons lengkap.

Parameter

  • Name
    mode
    Type
    string
    Wajib
    Description

    Kolom ini harus diatur ke "preview" saat membuat tugas preview.

  • Name
    prompt
    Type
    string
    Wajib
    Description

    Deskripsikan jenis objek dari model 3D tersebut. Maksimum 800 karakter.

  • Name
    model_type
    Type
    string
    default standard
    Description

    Tentukan jenis pembuatan mesh 3D.

    Nilai yang tersedia:

    • standard: Pembuatan mesh 3D detail tinggi biasa.
    • smart-topology: Pilih model Smart Topology dengan ai_model (meshy-t2).
    • lowpoly (usang): Menghasilkan mesh low-poly yang dioptimalkan untuk poligon yang lebih rapi. Kami merekomendasikan penggunaan smart-topology sebagai gantinya.

    Ketika smart-topology dipilih, should_remesh dan decimation_mode diabaikan, dan hanya topology: triangle yang diterima.

    Ketika lowpoly dipilih, ai_model, topology, target_polycount, dan should_remesh diabaikan.

  • Name
    ai_model
    Type
    string
    default latest
    Description

    ID model yang akan digunakan. Nilai yang tersedia bergantung pada model_type.

    Pembuatan standar (model_type: standard):

    • meshy-5, meshy-6, meshy-7, latest (Meshy 7)

    Pembuatan Smart Topology (model_type: smart-topology):

    • meshy-t2 (default): model Smart Topology — topology yang lebih rapi, bagian yang terpisah secara alami, keluaran triangle, dan jumlah wajah yang dapat Anda atur dengan target_polycount.
  • Name
    ultra_mode
    Type
    boolean
    default false
    Description

    Mengaktifkan pembuatan Ultra untuk geometri dengan fidelitas lebih tinggi dan detail permukaan yang lebih halus. Pembuatan memakan waktu lebih lama dan menambah 5 kredit.

    Hanya didukung ketika ai_model adalah meshy-7 (atau latest), dan hanya pada mode preview.

  • Name
    should_remesh
    Type
    boolean
    default false (meshy-6, meshy-7), true (others)
    Description

    Mengontrol apakah fase remesh diaktifkan. Untuk model dengan kualitas tertinggi, kami merekomendasikan mengatur should_remesh ke false.

Hanya berlaku ketika should_remesh = true
  • Name
    topology
    Type
    string
    default triangle
    Description

    Tentukan topology dari model yang dihasilkan.

    Nilai yang tersedia:

    • quad: Menghasilkan mesh yang didominasi quad.
    • triangle: Menghasilkan mesh triangle yang telah didesimasi.

    Keluaran Smart Topology hanya berupa triangle. Meminta quad bersamaan dengan ai_model: meshy-t2 akan mengembalikan kesalahan.

  • Name
    decimation_mode
    Type
    integer
    Description

    Aktifkan desimasi adaptif dengan mengatur tingkat jumlah poligon. Ketika diatur, target_polycount diabaikan.

    Nilai yang tersedia:

    • 1: Adaptif — jumlah poligon ultra.
    • 2: Adaptif — jumlah poligon tinggi.
    • 3: Adaptif — jumlah poligon sedang.
    • 4: Adaptif — jumlah poligon rendah.
  • Name
    target_polycount
    Type
    integer
    Description

    Jumlah poligon (wajah) target pada keluaran. Jumlah aktual dapat menyimpang dari target tergantung pada geometrinya.

    target_polycount berlaku dalam dua kasus independen:

    • Remesh — dengan should_remesh: true pada model standard. Mesh akan di-remesh (didesimasi) ke jumlah ini secara perkiraan. Rentang 100 hingga 300.000, default 30.000. Jika decimation_mode diatur, maka itu diprioritaskan dan target_polycount diabaikan.
    • Smart Topology — dengan model_type: smart-topology dan ai_model: meshy-t2. Model dihasilkan langsung pada jumlah wajah ini; tidak ada proses remesh yang berjalan dan should_remesh tidak diperlukan. Rentang 100 hingga 15.000, default 4.000.
  • Name
    symmetry_mode
    Type
    string
    ⚠ usang
    default auto
    Description

    Usang. Parameter ini tidak lagi memengaruhi keluaran.

    Kolom symmetry_mode mengontrol perilaku simetri selama proses pembuatan model.

    Nilai yang valid adalah:

    • off: Menonaktifkan simetri.
    • auto: Secara otomatis menentukan dan menerapkan simetri berdasarkan geometri masukan.
    • on: Memaksakan simetri selama pembuatan.
  • Name
    pose_mode
    Type
    string
    default ""
    Description

    Tentukan mode pose untuk model yang dihasilkan.

    Nilai yang tersedia:

    • a-pose: Menghasilkan model dalam pose A.
    • t-pose: Menghasilkan model dalam pose T.
    • "" (string kosong): Tidak ada pose spesifik yang diterapkan.
  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ usang
    default false
    Description

    Gunakan pose_mode sebagai gantinya. Apakah akan menghasilkan model dalam pose A/T.

  • Name
    art_style
    Type
    string
    ⚠ usang
    default realistic
    Description

    Tidak didukung oleh Meshy-6. Permintaan yang menggunakan Meshy-6 akan mengabaikan art_style, dan beberapa kombinasi dapat menyebabkan kesalahan. Nilai yang tersedia: realistic, sculpture.

    enable_pbr harus diatur ke false saat menggunakan gaya Sculpture, karena gaya Sculpture menghasilkan set peta PBR-nya sendiri.

  • Name
    moderation
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, konten masukan akan secara otomatis disaring untuk konten yang berpotensi berbahaya. Jika konten berbahaya terdeteksi, tugas tidak akan dilanjutkan ke pembuatan.

    Teks dari prompt akan disaring.

  • Name
    target_formats
    Type
    string[]
    Description

    Menentukan format berkas 3D mana yang akan disertakan dalam keluaran. Hanya format yang diminta yang akan dihasilkan dan dikembalikan, yang dapat mengurangi waktu penyelesaian tugas. Ketika dihilangkan, semua format yang didukung akan disertakan.

    Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf

    Ketika dihilangkan, semua format kecuali 3mf akan dihasilkan. 3mf hanya disertakan ketika ditentukan secara eksplisit.

  • Name
    alpha_thumbnail
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, tugas juga akan me-render versi latar belakang transparan (RGBA) dari preview dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Kolom thumbnail_url yang sudah ada tidak berubah.

  • Name
    auto_size
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, layanan menggunakan penglihatan AI untuk secara otomatis memperkirakan tinggi objek di dunia nyata dan mengubah ukuran model sesuai dengan itu. Titik asal akan default ke bottom kecuali origin_at diatur secara eksplisit.

Hanya berlaku ketika auto_size = true
  • Name
    origin_at
    Type
    string
    default bottom
    Description

    Posisi titik asal ketika auto_size diaktifkan.

    Nilai yang tersedia: bottom, center.

Returns

Properti result pada respons berisi id tugas dari tugas Teks ke 3D yang baru dibuat.

Failure Modes

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • Parameter hilang: Parameter yang diperlukan (misalnya, prompt, mode) tidak ada.
    • Parameter tidak valid: art_style bukan salah satu nilai yang diizinkan.
    • Prompt terlalu panjang: prompt melebihi batas karakter.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Silakan periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak cukup untuk melakukan tugas ini.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi batas laju Anda.

Request

POST
/openapi/v2/text-to-3d
# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with remesh and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
POST/openapi/v2/text-to-3d

Create a Text to 3D Refine Task

Endpoint ini membuat tugas Teks ke 3D refine, yang menerapkan tekstur pada mesh preview yang telah selesai. Anda harus menyediakan preview_task_id dari tugas preview yang berhasil. Ini adalah langkah kedua dari alur kerja dua langkah.

Parameter

  • Name
    mode
    Type
    string
    Wajib
    Description

    Kolom ini harus diatur ke "refine" saat membuat tugas refine.

  • Name
    preview_task_id
    Type
    string
    Wajib
    Description

    ID tugas preview yang bersesuaian.

    Status dari tugas preview yang diberikan harus SUCCEEDED.

  • Name
    enable_pbr
    Type
    boolean
    default false
    Description

    Hasilkan peta PBR (metallic, roughness, normal) selain warna dasar. Peta emisi juga disertakan ketika ai_model adalah meshy-6, kecuali pada texture_resolution: 8k (peta emisi tidak dihasilkan). meshy-7 (dan latest) tidak menghasilkan peta emisi.

  • Name
    texture_resolution
    Type
    string
    default 2k
    Description

    Resolusi tekstur warna dasar. Salah satu dari 2k (2048×2048), 4k (4096×4096), atau 8k (8192×8192). Resolusi yang lebih tinggi menangkap detail permukaan yang lebih banyak. Hanya berlaku untuk mode refine.

    4k dan 8k memerlukan ai_model meshy-6, meshy-7, atau latest. Pada 8k, peta emisi tidak dihasilkan.

  • Name
    hd_texture
    Type
    boolean
    ⚠ usang
    default false
    Description

    Gunakan texture_resolution sebagai gantinya — setara dengan texture_resolution: "4k". Jika keduanya diatur, texture_resolution akan diprioritaskan.

  • Name
    texture_prompt
    Type
    string
    Description

    Berikan prompt teks tambahan untuk memandu proses pemberian tekstur. Maksimal 800 karakter.

  • Name
    texture_image_url
    Type
    string
    Description

    Berikan gambar 2d untuk memandu proses pemberian tekstur. Kami saat ini mendukung format .jpg, .jpeg, dan .png.

    Ada dua cara untuk menyediakan gambar:

    • URL yang dapat diakses publik: URL yang dapat diakses dari internet publik
    • Data URI: Data URI gambar yang dienkode base64. Contoh Data URI: data:image/jpeg;base64,<data gambar terenkode base64 Anda>

    Pemberian tekstur gambar mungkin tidak bekerja secara optimal jika terdapat perbedaan geometri yang signifikan antara aset asli dan gambar yang diunggah. Hanya salah satu dari texture_image_url atau texture_prompt yang dapat digunakan untuk memandu proses pemberian tekstur. Jika kedua parameter diberikan, maka texture_prompt akan digunakan secara default untuk memberi tekstur pada model.

  • Name
    ai_model
    Type
    string
    default inherited from the preview task
    Description

    ID model yang digunakan untuk refine. Nilai yang tersedia: meshy-5, meshy-6, meshy-7, latest (Meshy 7).

    Hilangkan parameter ini untuk mewarisi model yang digunakan oleh tugas preview, sehingga preview dan refine-nya tetap menggunakan model yang sama secara end to end. Berikan nilai eksplisit untuk mengabaikan pewarisan tersebut.

    latest yang eksplisit diselesaikan di sini persis seperti pada tugas preview (saat ini Meshy 7), sehingga preview latest dan refine latest-nya selalu menggunakan model tekstur yang sama.

  • Name
    moderation
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, konten input akan secara otomatis diperiksa untuk konten yang berpotensi berbahaya. Jika konten berbahaya terdeteksi, tugas tidak akan dilanjutkan ke tahap generasi.

    Baik teks dari texture_prompt maupun gambar dari texture_image_url akan diperiksa.

  • Name
    remove_lighting
    Type
    boolean
    default true
    Description

    Menghapus sorotan (highlight) dan bayangan dari tekstur warna dasar, menghasilkan hasil yang lebih bersih yang bekerja lebih baik dalam pengaturan pencahayaan kustom.

    Hanya berlaku ketika ai_model adalah meshy-6. Pada meshy-7 (dan latest) parameter ini diterima tetapi diabaikan.

  • Name
    target_formats
    Type
    string[]
    Description

    Menentukan format berkas 3D mana yang disertakan dalam hasil. Hanya format yang diminta yang akan dihasilkan dan dikembalikan, yang dapat mengurangi waktu penyelesaian tugas. Jika dihilangkan, semua format yang didukung akan disertakan.

    Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf

    Jika dihilangkan, semua format kecuali 3mf akan dihasilkan. 3mf hanya disertakan ketika ditentukan secara eksplisit.

  • Name
    alpha_thumbnail
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, tugas ini juga merender versi latar belakang transparan (RGBA) dari preview dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Kolom thumbnail_url yang sudah ada tidak berubah.

  • Name
    auto_size
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, layanan menggunakan AI vision untuk secara otomatis memperkirakan tinggi objek di dunia nyata dan mengubah ukuran model sesuai dengan itu. Titik asal akan default ke bottom kecuali origin_at diatur secara eksplisit.

Hanya berlaku ketika auto_size = true
  • Name
    origin_at
    Type
    string
    default bottom
    Description

    Posisi titik asal ketika auto_size diaktifkan.

    Nilai yang tersedia: bottom, center.

Returns

Properti result pada respons berisi id tugas dari tugas Teks ke 3D yang baru dibuat.

Mode Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • ID tugas tidak valid: preview_task_id tidak valid atau tidak ada.
    • Tugas belum siap: Tugas preview belum berhasil.
    • Ketidakcocokan model: Model AI tugas preview tidak kompatibel dengan model refine yang diminta.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Silakan periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak cukup untuk melakukan tugas ini.

  • Name
    404 - Not Found
    Description

    Tugas preview yang ditentukan oleh preview_task_id tidak ditemukan.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melampaui batas laju Anda.

Request

POST
/openapi/v2/text-to-3d
# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v2/text-to-3d/:id

Mengambil Tugas Text to 3D

Endpoint ini memungkinkan Anda mengambil tugas Text to 3D berdasarkan id tugas yang valid. Lihat The Text to 3D Task Object untuk melihat properti apa saja yang disertakan dalam objek tugas Text to 3D.

Endpoint ini berfungsi untuk tugas preview maupun refine.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk tugas Text to 3D yang ingin diambil.

Returns

Respons berisi objek tugas Text to 3D. Lihat bagian The Text to 3D Task Object untuk detailnya.

Contoh

ModeContoh Model
PreviewPreview model
RefineRefined model

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}
DELETE/openapi/v2/text-to-3d/:id

Menghapus Task Teks ke 3D

Endpoint ini secara permanen menghapus task Teks ke 3D, termasuk semua model dan data yang terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Path

  • Name
    id
    Type
    path
    Description

    ID dari task Teks ke 3D yang akan dihapus.

Returns

Mengembalikan 200 OK jika berhasil.

Request

DELETE
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.
GET/openapi/v2/text-to-3d

List Text to 3D Tasks

Endpoint ini memungkinkan Anda mengambil daftar tugas Teks ke 3D.

Parameter

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Nomor halaman untuk paginasi.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Batas ukuran halaman. Maksimum yang diizinkan adalah 50 item.

  • Name
    sort_by
    Type
    string
    Description

    Kolom untuk diurutkan.

    Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan secara ascending.
    • -created_at: Urutkan berdasarkan waktu pembuatan secara descending.

Returns

Mengembalikan daftar berpaginasi dari The Text to 3D Task Objects.

Request

GET
/openapi/v2/text-to-3d
curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]
GET/openapi/v2/text-to-3d/:id/stream

Stream a Text to 3D Task

Endpoint ini melakukan streaming pembaruan secara real-time untuk task Teks ke 3D menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal unik untuk task Teks ke 3D yang akan di-streaming.

Returns

Mengembalikan sebuah stream dari The Text to 3D Task Objects sebagai Server-Sent Events.

Untuk task dengan status PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan kolom progress dan status yang diperlukan.

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"texture_urls": [
  {
    "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
    "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
    "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
    "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
    "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
  }
],
"preceding_tasks": 0,
"task_error": {

  "message": ""

},

"consumed_credits": 20
}

The Text to 3D Task Object

Objek Text to 3D Task adalah unit kerja yang dilacak oleh Meshy untuk menghasilkan model 3D dari input teks. Ada dua tahap Text to 3D API, preview dan refine. Tahap preview digunakan untuk menghasilkan model 3D yang hanya berupa mesh, dan tahap refine digunakan untuk menghasilkan model 3D bertekstur berdasarkan hasil tahap preview.

Objek ini memiliki properti berikut:

Properties

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi unik untuk task. Meskipun kami menggunakan UUID yang dapat diurutkan-k (k-sortable) untuk id task sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis task Text to 3D. Kemungkinan nilainya adalah text-to-3d-preview untuk task tahap preview dan text-to-3d-refine untuk task tahap refine.

  • Name
    model_urls
    Type
    object
    Description

    URL yang dapat diunduh untuk file model 3D bertekstur yang dihasilkan oleh Meshy. Properti untuk suatu format akan dihilangkan jika format tersebut tidak dihasilkan, alih-alih mengembalikan string kosong.

    • Name
      glb
      Type
      string
      Description

      URL yang dapat diunduh untuk file GLB.

    • Name
      fbx
      Type
      string
      Description

      URL yang dapat diunduh untuk file FBX.

    • Name
      usdz
      Type
      string
      Description

      URL yang dapat diunduh untuk file USDZ.

    • Name
      obj
      Type
      string
      Description

      URL yang dapat diunduh untuk file OBJ.

    • Name
      mtl
      Type
      string
      Description

      URL yang dapat diunduh untuk file MTL.

    • Name
      stl
      Type
      string
      Description

      URL yang dapat diunduh untuk file STL.

    • Name
      3mf
      Type
      string
      Description

      URL yang dapat diunduh untuk file 3MF. Hanya ada ketika 3mf diminta melalui target_formats.

  • Name
    prompt
    Type
    string
    Description

    Ini adalah prompt yang tidak dimodifikasi yang digunakan untuk membuat task.

  • Name
    negative_prompt
    Type
    string
    ⚠ usang
    Description

    Dipertahankan untuk kompatibilitas ke belakang. Kolom ini tidak memiliki dampak fungsional pada model yang dihasilkan.

  • Name
    art_style
    Type
    string
    ⚠ usang
    Description

    art_style yang tidak dimodifikasi yang digunakan untuk membuat task preview. Tidak didukung oleh Meshy-6.

  • Name
    texture_richness
    Type
    string
    ⚠ usang
    Description

    Dipertahankan untuk kompatibilitas ke belakang. Kolom ini tidak memiliki dampak fungsional pada model yang dihasilkan.

  • Name
    texture_prompt
    Type
    string
    Description

    Prompt teks tambahan yang diberikan untuk memandu proses texturing selama tahap refine.

  • Name
    ultra_mode
    Type
    boolean
    Description

    Mencerminkan nilai ultra_mode yang digunakan saat task preview dibuat. Hanya ada untuk task preview meshy-7 (atau latest) yang secara eksplisit menetapkan ultra_mode; jika tidak, kolom ini dihilangkan.

  • Name
    texture_image_url
    Type
    string
    Description

    URL yang dapat diunduh untuk gambar tekstur yang digunakan untuk memandu proses texturing.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL yang dapat diunduh untuk gambar thumbnail dari file model.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL yang dapat diunduh untuk versi latar belakang transparan (RGBA) dari thumbnail_url. Hanya ada ketika task dibuat dengan alpha_thumbnail: true dan preview transparan berhasil dirender; jika tidak, kolom ini dihilangkan.

  • Name
    video_url
    Type
    string
    ⚠ usang
    Description

    URL yang dapat diunduh untuk video preview. Akan dihapus pada rilis mendatang.

  • Name
    progress
    Type
    integer
    Description

    Progress dari task. Jika task belum dimulai, properti ini bernilai 0. Setelah task berhasil, nilai ini akan menjadi 100.

  • Name
    started_at
    Type
    timestamp
    Description

    Stempel waktu saat task dimulai, dalam milidetik. Jika task belum dimulai, properti ini bernilai 0.

    Stempel waktu merepresentasikan jumlah milidetik yang telah berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Misalnya, Jumat, 1 September 2023 pukul 12:00:00 GMT direpresentasikan sebagai 1693569600000. Ini berlaku untuk semua stempel waktu dalam Meshy API.

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu saat task dibuat, dalam milidetik.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat task selesai, dalam milidetik. Jika task belum selesai, properti ini bernilai 0.

  • Name
    status
    Type
    string
    Description

    Status dari task. Kemungkinan nilainya adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    texture_urls
    Type
    array
    Description

    Sebuah array objek URL tekstur yang dihasilkan dari task. Biasanya ini hanya berisi satu objek URL tekstur. Setiap URL tekstur memiliki properti berikut:

    • Name
      base_color
      Type
      string
      Description

      URL yang dapat diunduh untuk gambar peta warna dasar (base color map).

    • Name
      metallic
      Type
      string
      Description

      URL yang dapat diunduh untuk gambar peta metallic.

      Jika task dibuat dengan enable_pbr: false, properti ini akan dihilangkan.

    • Name
      normal
      Type
      string
      Description

      URL yang dapat diunduh untuk gambar normal map.

      Jika task dibuat dengan enable_pbr: false, properti ini akan dihilangkan.

    • Name
      roughness
      Type
      string
      Description

      URL yang dapat diunduh untuk gambar peta roughness.

      Jika task dibuat dengan enable_pbr: false, properti ini akan dihilangkan.

    • Name
      emission
      Type
      string
      Description

      URL yang dapat diunduh untuk gambar peta emission.

      Jika task dibuat dengan enable_pbr: false, atau ai_model adalah meshy-5, properti ini akan dihilangkan.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah task yang mendahului.

    Nilai dari kolom ini hanya bermakna jika status task adalah PENDING.

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan untuk task yang gagal. Lihat Kesalahan untuk referensi lengkap objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang digunakan oleh task ini. Ada ketika status task adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk task FAILED (kredit dikembalikan jika gagal).

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}