Text to 3D API

Text to 3D API adalah fitur yang memungkinkan Anda mengintegrasikan kemampuan Teks ke 3D milik Meshy ke dalam aplikasi Anda sendiri. Pada bagian ini, Anda akan menemukan semua informasi yang Anda butuhkan untuk memulai menggunakan API ini.

Teks ke 3D menggunakan alur kerja dua tahap. 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 tahap ini menggunakan endpoint yang sama.

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

Create a Text to 3D Preview Task

Endpoint ini membuat tugas Teks ke 3D preview, 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

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

  • Name
    prompt
    Type
    string
    Wajib
    Description

    Jelaskan jenis objek apa yang menjadi 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 reguler dengan detail tinggi.
    • 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 menyarankan untuk menggunakan 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 digunakan. Nilai yang tersedia bergantung pada model_type.

    Pembuatan standar (model_type: standard):

    • meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
    • meshy-7 (usang): gunakan meshy-7.1 sebagai gantinya.

    Pembuatan Smart Topology (model_type: smart-topology):

    • meshy-t2 (default): model Smart Topology — topology yang lebih rapi, bagian yang terpisah secara alami, output triangle, dan jumlah face yang dapat diatur dengan target_polycount.
  • Name
    geometry_resolution
    Type
    string
    default standard
    Description

    Tahap pembuatan geometri. 2k menjalankan tahap Ultra pada 2048³; 4k menjalankannya pada 4096³ untuk detail permukaan yang paling halus.

    Nilai yang tersedia: standard, 2k, 4k

    Hanya didukung pada mode preview. Memerlukan meshy-7.1 atau latest.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ usang
    default false
    Description

    Gunakan geometry_resolution sebagai gantinya. ultra_mode: true setara dengan geometry_resolution: "2k".

  • Name
    should_remesh
    Type
    boolean
    default false (Meshy 6 and Meshy 7 models), true (others)
    Description

    Mengontrol apakah akan mengaktifkan fase remesh. Untuk model dengan kualitas tertinggi, kami menyarankan untuk 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.

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

  • Name
    decimation_mode
    Type
    integer
    Description

    Mengaktifkan desimasi adaptif dengan mengatur level 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

    Target jumlah poligon (face) pada output. Jumlah sebenarnya mungkin berbeda dari target tergantung pada geometrinya.

    target_polycount berlaku dalam dua kasus yang independen:

    • Remesh — dengan should_remesh: true pada model standard. Mesh diremesh (didesimasi) menjadi sekitar jumlah ini. Rentang 100 hingga 300.000, default 30.000. Jika decimation_mode diatur, itu memiliki prioritas dan target_polycount diabaikan.
    • Smart Topology — dengan model_type: smart-topology dan ai_model: meshy-t2. Model dihasilkan langsung dengan jumlah face ini; tidak ada 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 output.

    Bidang 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 input.
    • on: Memberlakukan 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 error. 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 input akan secara otomatis disaring untuk konten yang berpotensi berbahaya. Jika konten berbahaya terdeteksi, tugas tidak akan berlanjut ke tahap pembuatan.

    Teks dari prompt akan disaring.

  • Name
    target_formats
    Type
    string[]
    Description

    Menentukan format file 3D mana yang akan disertakan dalam output. 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 juga akan me-render versi latar belakang transparan (RGBA) dari preview dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Bidang 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 dari 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:

    • Parameter hilang: Parameter yang diperlukan (misalnya, prompt, mode) hilang.
    • Parameter tidak valid: art_style bukan salah satu dari nilai yang diperbolehkan.
    • Prompt terlalu panjang: prompt melebihi batas karakter.
    • Model tidak didukung untuk low poly: ai_model: "meshy-6-lite" tidak mendukung model_type: "lowpoly".
    • Model tidak didukung untuk Ultra: geometry_resolution memerlukan meshy-7.1 atau latest.
  • 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 Ultra 4K geometry, 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",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "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

Membuat Task Refine Text to 3D

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

Parameter

  • Name
    mode
    Type
    string
    Wajib
    Description

    Field ini harus diatur ke "refine" saat membuat task refine.

  • Name
    preview_task_id
    Type
    string
    Wajib
    Description

    ID task preview yang bersesuaian.

    Status dari task preview yang diberikan harus SUCCEEDED.

  • Name
    enable_pbr
    Type
    boolean
    default false
    Description

    Menghasilkan peta PBR (metallic, roughness, normal) selain base color. Peta emission juga disertakan ketika ai_model adalah meshy-6, kecuali pada texture_resolution: 8k (tidak dihasilkan peta emission). meshy-6-lite, meshy-7.1, dan latest tidak menghasilkan peta emission.

  • Name
    texture_resolution
    Type
    string
    default 2k
    Description

    Resolusi tekstur base color. 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.1, atau latest. Pada 8k, tidak dihasilkan peta emission.

  • Name
    hd_texture
    Type
    boolean
    ⚠ usang
    default false
    Description

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

  • Name
    texture_prompt
    Type
    string
    Description

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

  • Name
    texture_image_url
    Type
    string
    Description

    Berikan gambar 2d untuk memandu proses pembuatan tekstur. Saat ini kami 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 dikodekan base64. Contoh data URI: data:image/jpeg;base64,<data gambar terenkode base64 Anda>

    Pembuatan 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 pembuatan tekstur. Jika kedua parameter disediakan, maka texture_prompt yang akan digunakan secara default untuk membuat tekstur model.

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

    ID model yang digunakan untuk refine.

    Nilai yang tersedia:

    • meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
    • meshy-7 (usang): gunakan meshy-7.1 sebagai gantinya.

    Hilangkan parameter ini agar mewarisi model yang digunakan oleh task preview, sehingga preview dan refine-nya tetap menggunakan model yang sama dari awal hingga akhir. Berikan nilai eksplisit untuk menimpa pewarisan tersebut.

    latest yang eksplisit akan diresolusi di sini persis seperti pada task preview (saat ini Meshy 7.1), sehingga preview latest dan refine latest-nya akan selalu menggunakan model tekstur yang sama.

  • Name
    moderation
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, konten input akan secara otomatis diperiksa untuk mendeteksi konten yang berpotensi berbahaya. Jika konten berbahaya terdeteksi, task 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

    Menghilangkan highlight dan bayangan dari tekstur base color, menghasilkan hasil yang lebih bersih dan bekerja lebih baik di bawah pengaturan pencahayaan kustom.

    Hanya berlaku ketika ai_model adalah meshy-6; model lain akan mengabaikannya.

  • Name
    target_formats
    Type
    string[]
    Description

    Menentukan format file 3D mana yang akan disertakan dalam output. Hanya format yang diminta yang akan dihasilkan dan dikembalikan, yang dapat mengurangi waktu penyelesaian task. 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, task tersebut juga akan merender versi latar belakang transparan (RGBA) dari preview dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Field thumbnail_url yang sudah ada tidak berubah.

  • Name
    auto_size
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, layanan akan 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 task dari task Text to 3D yang baru dibuat.

Mode Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • ID task tidak valid: preview_task_id tidak valid atau tidak ada.
    • Task belum siap: Task preview belum berhasil.
    • Ketidakcocokan model: Model AI dari task 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 mencukupi untuk melakukan task ini.

  • Name
    404 - Not Found
    Description

    Task preview yang ditentukan oleh preview_task_id tidak ditemukan.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi 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

    Pengidentifikasi unik untuk tugas Text to 3D yang akan diambil.

Hasil

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

Hapus Task Teks ke 3D

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

Path Parameters

  • Name
    id
    Type
    path
    Description

    ID dari task Teks ke 3D yang akan dihapus.

Status Task

Task yang masih berstatus PENDING akan dihapus dan kredit yang digunakan saat pembuatan akan dikembalikan.

Task yang sudah berstatus IN_PROGRESS tidak dapat dihapus: permintaan akan ditolak dengan 409 Conflict dan task tetap berjalan. Kredit untuk task yang sudah mulai diproses oleh worker tidak dapat dikembalikan, sehingga menghapusnya di tengah proses akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

Task dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) akan dihapus tanpa pengembalian kredit.

Returns

Mengembalikan 200 OK jika berhasil, atau 409 Conflict jika task berstatus IN_PROGRESS.

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

// 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/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 100 item.

  • Name
    sort_by
    Type
    string
    Description

    Kolom untuk mengurutkan.

    Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan secara menaik.
    • -created_at: Urutkan berdasarkan waktu pembuatan secara menurun.

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 stream berisi The Text to 3D Task Objects sebagai Server-Sent Events.

Untuk task berstatus PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan bidang 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 Task Teks ke 3D adalah unit kerja yang dilacak oleh Meshy untuk menghasilkan model 3D dari input teks. Terdapat dua tahap dalam Teks ke 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 dari tahap preview.

Objek ini memiliki properti berikut:

Properties

  • Name
    id
    Type
    string
    Description

    Identifier unik untuk task tersebut. Meskipun kami menggunakan k-sortable UUID untuk id task sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Tipe dari task Teks ke 3D. Nilai yang mungkin 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, bukan 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 muncul saat 3mf diminta melalui target_formats.

  • Name
    prompt
    Type
    string
    Description

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

  • Name
    negative_prompt
    Type
    string
    ⚠ usang
    Description

    Dipertahankan untuk kompatibilitas mundur. Bidang ini tidak memiliki dampak fungsional terhadap 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 mundur. Bidang ini tidak memiliki dampak fungsional terhadap model yang dihasilkan.

  • Name
    texture_prompt
    Type
    string
    Description

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

  • Name
    ultra_mode
    Type
    boolean
    ⚠ usang
    Description

    Usang; gunakan geometry_resolution sebagai gantinya.

  • Name
    geometry_resolution
    Type
    string
    Description

    Tingkatan Ultra yang digunakan task preview (2k atau 4k); dihilangkan untuk standard.

  • Name
    texture_image_url
    Type
    string
    Description

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

  • 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 muncul saat task dibuat dengan alpha_thumbnail: true dan preview transparan berhasil dirender; jika tidak, bidang ini akan 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 tersebut. Jika task belum dimulai, properti ini akan bernilai 0. Setelah task berhasil, ini akan menjadi 100.

  • Name
    started_at
    Type
    timestamp
    Description

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

    Stempel waktu merepresentasikan jumlah milidetik yang telah berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Sebagai contoh, Jumat, 1 September 2023 12:00:00 PM GMT direpresentasikan sebagai 1693569600000. Ini berlaku untuk semua stempel waktu di 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 akan bernilai 0.

  • Name
    status
    Type
    string
    Description

    Status dari task tersebut. Nilai yang mungkin 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 tersebut. 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.

    • 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-6-lite, properti ini akan dihilangkan.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah task sebelumnya yang mendahului.

    Nilai bidang 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 dikonsumsi oleh task ini. Muncul saat status task adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk task FAILED (kredit dikembalikan saat 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
}