Teks ke 3D API

Hasilkan model 3D dari prompt teks di aplikasi Anda sendiri.

Teks ke 3D bekerja dalam dua langkah. Pertama, buat tugas preview (mode: "preview") untuk menghasilkan mesh 3D tanpa tekstur, sehingga Anda dapat memeriksa bentuknya. Kemudian, kirim ID tugas preview yang berhasil ke tugas refine (mode: "refine") untuk memberi tekstur pada mesh tersebut. Kedua langkah ini menggunakan endpoint yang sama.

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

Buat tugas preview Text to 3D

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, kirim ID tugasnya dalam tugas refine untuk memberi tekstur pada mesh tersebut. Lihat Buat tugas refine Text to 3D. Untuk skema respons lengkap, lihat Objek tugas Text to 3D.

Tugas berjalan di latar belakang. Untuk mengetahui berapa lama biasanya sebuah tugas berjalan, lihat Waktu pemrosesan.

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"
}

Parameter

Name
mode
Type
string
Wajib
Description
Tahap dari alur kerja dua langkah. Kirim preview untuk membuat tugas preview.
Name
prompt
Type
string
Wajib
Description
Teks yang mendeskripsikan objek yang akan dihasilkan, hingga 800 karakter. Teks yang lebih panjang mengembalikan 400.
Name
model_type
Type
string
default standard
Description
Jenis mesh 3D yang akan dihasilkan.
Nilai yang tersedia:
- standard: mesh 3D dengan detail tinggi
- smart-topology: mesh Smart Topology. Pilih model dengan ai_model (meshy-t2 atau meshy-t2.5).
Dengan smart-topology, Meshy mengabaikan should_remesh dan decimation_mode, dan hanya menerima topology: triangle.
Name
ai_model
Type
string
default latest
Description
Model AI yang menghasilkan model 3D. Nilai yang tersedia tergantung pada model_type.
Model standar (model_type: standard):
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (usang): kirim meshy-7.1 sebagai gantinya
Model Smart Topology (model_type: smart-topology):
- meshy-t2: topology yang lebih bersih, bagian yang terpisah secara native, output triangle, dan jumlah face yang Anda atur dengan target_polycount
- meshy-t2.5 (default): detail yang lebih tajam untuk aset game, output triangle, dan jumlah face yang Anda atur dengan target_polycount
Lihat Model untuk mengetahui model mana yang cocok untuk proyek Anda, seperti karakter game atau cetakan 3D.
Name
geometry_resolution
Type
string
default standard
Description
Tahap generasi geometri. Hanya berlaku untuk tugas preview. Refine dengan parameter ini mengembalikan 400.
Nilai yang tersedia:
- standard
- 2k: menjalankan tahap Ultra pada 2048³
- 4k: menjalankan tahap Ultra pada 4096³, untuk detail permukaan yang lebih halus
2k membutuhkan meshy-7.1, latest, atau meshy-7 yang usang. 4k membutuhkan meshy-7.1 atau latest. Model lain mengembalikan 400.
Name
ultra_mode
Type
boolean
⚠ usang
default false
Description
Kirim geometry_resolution sebagai gantinya. ultra_mode: true sama dengan geometry_resolution: "2k".
Name
should_remesh
Type
boolean
default true (meshy-6-lite), false (other models)
Description
Apakah akan melakukan remesh pada model setelah pembuatan. Untuk model 3D dengan kualitas tertinggi, kirim false.

Hanya berlaku ketika should_remesh = true

Name
topology
Type
string
default triangle
Description
Jenis face dari model yang di-remesh.
Nilai yang tersedia:
- quad: mesh yang didominasi quad
- triangle: mesh triangle yang didesimasi
Output Smart Topology hanya berupa triangle. Mengirim quad dengan ai_model meshy-t2 atau meshy-t2.5 mengembalikan 400.
Name
decimation_mode
Type
integer
Description
Jumlah face adaptif, berdasarkan level. Ketika Anda mengaturnya, Meshy mengabaikan target_polycount.
Nilai yang tersedia:
- 1: ultra
- 2: tinggi
- 3: sedang
- 4: rendah

Name
target_polycount
Type
integer
Description
Jumlah face yang ditargetkan. Hasilnya dapat berbeda dari target, tergantung pada geometrinya. Ini berlaku dalam dua kasus terpisah:
- Remesh: dengan should_remesh: true pada model standard. Meshy melakukan remesh (desimasi) pada mesh hingga mendekati jumlah ini. Jika Anda mengatur decimation_mode, Meshy menggunakannya dan mengabaikan target_polycount.
- Smart Topology: dengan model_type: smart-topology dan ai_model meshy-t2 atau meshy-t2.5. Meshy menghasilkan model langsung pada jumlah face ini. Tidak ada remesh yang berjalan, dan Anda tidak memerlukan should_remesh.
Tabel berikut menunjukkan rentang dan nilai default untuk setiap kasus:
Kasus Rentang Default
Remesh 100 hingga 300000 30000
meshy-t2 100 hingga 15000 4000
meshy-t2.5 100 hingga 30000 15000
Nilai di luar rentang mengembalikan 400.
Untuk aset game low-poly, gunakan model Smart Topology alih-alih melakukan remesh pada model standar. Lihat Model.

Kasus	Rentang	Default
Remesh	`100` hingga `300000`	`30000`
`meshy-t2`	`100` hingga `15000`	`4000`
`meshy-t2.5`	`100` hingga `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ usang
default auto
Description
Hilangkan parameter ini. Parameter ini tidak memengaruhi output.
Nilai yang tersedia:
- off: menonaktifkan simetri
- auto: menerapkan simetri berdasarkan geometri input
- on: memaksakan simetri selama pembuatan
Name
pose_mode
Type
string
default ""
Description
Pose dari model yang dihasilkan.
Nilai yang tersedia:
- a-pose: pose A
- t-pose: pose T
- "" (string kosong): tidak ada pose tertentu
Name
is_a_t_pose
Type
boolean
⚠ usang
default false
Description
Kirim pose_mode sebagai gantinya. Apakah model akan dihasilkan dalam pose A atau pose T.
Name
art_style
Type
string
⚠ usang
default realistic
Description
Hilangkan parameter ini. Meshy mengabaikannya.
Name
moderation
Type
boolean
default false
Description
Apakah akan memeriksa prompt untuk konten berbahaya sebelum menghasilkan. Jika Meshy mendeteksi konten berbahaya, permintaan mengembalikan 400 dan Meshy tidak membuat tugas.
Name
target_formats
Type
string[]
Description
Format file yang akan dihasilkan. Meshy hanya menghasilkan dan mengembalikan format ini, yang dapat mempersingkat tugas. Jika Anda tidak menyertakannya, Meshy menghasilkan setiap format kecuali 3mf, yang hanya dihasilkan ketika Anda memintanya.
Nilai yang tersedia:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
default false
Description
Apakah juga akan merender preview dengan latar belakang transparan (RGBA), dikembalikan di alpha_thumbnail_url saat Anda mengambil tugas. thumbnail_url tidak berubah.
Name
auto_size
Type
boolean
default false
Description
Apakah akan memperkirakan tinggi objek di dunia nyata menggunakan AI vision dan mengubah ukuran model sesuai dengan itu. Meshy menempatkan titik asal di bagian bawah kecuali Anda mengatur origin_at.

Hanya berlaku ketika auto_size = true

Name
origin_at
Type
string
default bottom
Description
Di mana menempatkan titik asal model, bottom atau center.

Mengembalikan

Kolom result dari respons menyimpan ID dari tugas Text to 3D yang baru.

Mode kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Pesan kesalahan menunjukkan masalah apa yang ditemukan. Contohnya:
- Parameter hilang: Parameter yang diperlukan, seperti prompt atau mode, hilang.
- Prompt terlalu panjang: prompt melebihi batas karakter.
- Model tidak didukung untuk Ultra: geometry_resolution adalah 2k atau 4k, dengan ai_model yang tidak dapat menjalankannya.
Perbaiki permintaan, lalu kirim lagi. Lihat Kesalahan.
Name
401 - Unauthorized
Description
Kunci API hilang atau tidak valid. Periksa header Authorization.
Name
402 - Payment Required
Description
Contohnya:
- Kredit tidak cukup: Akun tidak memiliki cukup kredit untuk tugas ini, atau akun telah mencapai batas kredit. Periksa saldo kredit Anda, lalu coba lagi.
- Paket gratis: Membuat tugas memerlukan paket berbayar. Tingkatkan paket Anda di pengaturan langganan Anda, lalu coba lagi.
Name
403 - Forbidden
Description
Moderation konten memblokir prompt atau gambar input. Ubah input, lalu coba lagi.
Name
429 - Too Many Requests
Description
Anda melampaui batas laju Anda. Tunggu, lalu coba lagi. Lihat Batas laju.

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

Buat tugas refine Teks ke 3D

Membuat tugas refine Teks ke 3D, yang mem-tekstur mesh dari tugas preview yang telah selesai. Kirim ID dari tugas preview yang berhasil sebagai preview_task_id. Lihat Buat tugas preview Teks ke 3D. Ini adalah langkah kedua dari alur kerja dua langkah.

Tugas berjalan di latar belakang. Untuk mengetahui berapa lama biasanya tugas berjalan, lihat Waktu pemrosesan.

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
}'

# Refine with Meshy N1 from the preview's stored reference image
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",
  "ai_model": "meshy-n1"
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parameter

Name
mode
Type
string
Wajib
Description
Langkah dari alur kerja dua langkah. Kirim refine untuk membuat tugas refine.
Name
preview_task_id
Type
string
Wajib
Description
ID dari tugas preview yang akan di-tekstur. Tugas preview harus memiliki status SUCCEEDED.
Name
enable_pbr
Type
boolean
default false
Description
Apakah juga akan menghasilkan peta PBR (metallic, roughness, dan normal) beserta base color.
Dengan ai_model meshy-6, Meshy juga menghasilkan emission map, kecuali pada texture_resolution: 8k. meshy-6-lite, meshy-7, meshy-7.1, dan latest tidak menghasilkan emission map. Begitu juga dengan refine dari preview meshy-t2 atau meshy-t2.5 yang tidak menetapkan ai_model. Dengan ai_model: meshy-n1, true akan mengembalikan 400.
Name
texture_resolution
Type
string
default 2k
Description
Resolusi tekstur base color. Hanya berlaku untuk tugas refine. Preview dengan parameter ini akan mengembalikan 400.
Nilai yang tersedia:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Resolusi yang lebih tinggi menangkap lebih banyak detail permukaan. 4k dan 8k memerlukan ai_model meshy-6, meshy-7.1, atau latest. Dengan meshy-n1, nilai tersebut akan mengembalikan 400. Pada 8k, Meshy tidak menghasilkan emission map.
Name
hd_texture
Type
boolean
⚠ usang
default false
Description
Kirim texture_resolution sebagai gantinya. hd_texture: true sama dengan texture_resolution: "4k". Jika Anda mengirim keduanya, Meshy menggunakan texture_resolution.
Name
texture_prompt
Type
string
Description
Teks yang memandu proses texturing, hingga 800 karakter. Teks yang lebih panjang akan mengembalikan 400. Kirim texture_prompt atau texture_image_url, tidak keduanya. Jika Anda mengirim keduanya, Meshy menggunakan texture_prompt. Dengan ai_model: meshy-n1, mengirimkannya akan mengembalikan 400.
Name
texture_image_url
Type
string
Description
Gambar 2D yang memandu proses texturing, berupa URL publik atau data URI berenkode base64, seperti data:image/jpeg;base64,<your base64-encoded image data>.
Gambar harus berupa file .jpg, .jpeg, .png, atau .webp dengan ukuran maksimal 20 MB, minimal 32 piksel pada setiap sisi, dan maksimal 178.956.970 piksel (lebar × tinggi).
Dengan ai_model: meshy-n1, Meshy mem-tekstur dari gambar ini sebagai tampilan depan.
Texturing dari gambar mungkin tidak bekerja dengan baik jika bentuk dalam gambar sangat berbeda dari model.
Name
ai_model
Type
string
default inherited from the preview task
Description
Model AI yang mem-tekstur mesh.
Nilai yang tersedia:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-n1: tekstur base color 2K hanya dari gambar referensi. Tanpa prompt teks, tanpa peta PBR, tanpa 4K atau 8K.
- meshy-7 (usang): kirim meshy-7.1 sebagai gantinya
Biarkan kosong untuk menggunakan model dari tugas preview, sehingga preview dan refine-nya berjalan pada model yang sama secara menyeluruh. Kirim sebuah nilai untuk menggantinya. latest yang ditetapkan secara eksplisit akan diselesaikan dengan cara yang sama seperti pada tugas preview, sehingga preview latest dan refine latest-nya selalu menggunakan model tekstur yang sama.
Dengan meshy-n1, Meshy mem-tekstur dari texture_image_url. Tanpa itu, Meshy menggunakan gambar referensi yang disimpan oleh preview meshy-7.1 atau latest. Preview lainnya akan mengembalikan 400 kecuali Anda mengirim texture_image_url. Preview dapat memiliki paling banyak 7.999.999 segitiga. Preview yang di-remesh menjadi quad akan mengembalikan 400.
Name
moderation
Type
boolean
default false
Description
Apakah akan menyaring texture_prompt dan texture_image_url untuk konten berbahaya sebelum menghasilkan. Jika Meshy mendeteksi konten berbahaya, permintaan akan mengembalikan 400 dan Meshy tidak membuat tugas.
Name
remove_lighting
Type
boolean
default true
Description
Apakah akan menghapus highlight dan bayangan dari tekstur base color. Hasil yang lebih bersih bekerja lebih baik di bawah pencahayaan kustom.
Hanya berlaku jika ai_model adalah meshy-6. meshy-7.1 dan latest menerimanya tetapi mengabaikannya, begitu juga dengan refine dari preview meshy-t2 atau meshy-t2.5 yang tidak menetapkan ai_model. Mengirimkannya dengan meshy-6-lite akan mengembalikan 400. Dengan meshy-n1, true akan mengembalikan 400.
Name
target_formats
Type
string[]
Description
Format file yang akan dihasilkan. Meshy hanya menghasilkan dan mengembalikan format-format ini, yang dapat mempersingkat tugas. Jika Anda tidak menyertakannya, Meshy menghasilkan setiap format kecuali 3mf, yang hanya dihasilkan jika Anda memintanya.
Nilai yang tersedia:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
default false
Description
Apakah juga akan merender preview dengan latar belakang transparan (RGBA), dikembalikan dalam alpha_thumbnail_url ketika Anda mengambil tugas. thumbnail_url tidak berubah.
Name
auto_size
Type
boolean
default false
Description
Apakah akan memperkirakan tinggi objek di dunia nyata menggunakan AI vision dan mengubah ukuran model sesuai dengan itu. Meshy menempatkan titik asal di bagian bawah kecuali Anda menetapkan origin_at.

Hanya berlaku ketika auto_size = true

Name
origin_at
Type
string
default bottom
Description
Di mana menempatkan titik asal model, bottom atau center.

Hasil yang dikembalikan

Kolom result pada respons menyimpan ID dari tugas Teks ke 3D yang baru.

Mode kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Pesan kesalahan menunjukkan masalah apa yang ditemukan. Misalnya:
- ID tugas tidak valid: preview_task_id tidak valid, atau tidak cocok dengan salah satu tugas preview Anda.
- Tugas belum siap: Tugas preview belum berhasil.
- Ketidakcocokan model: Model AI dari tugas preview tidak bekerja dengan model refine yang diminta.
- Model tidak didukung untuk remove_lighting: remove_lighting dikirim dengan ai_model: "meshy-6-lite".
- Tidak ada gambar referensi untuk Meshy N1: ai_model: meshy-n1 dikirim tanpa texture_image_url, dan preview tidak memiliki gambar referensi yang dapat digunakan oleh Meshy N1. Kirim texture_image_url.
- Preview quad untuk Meshy N1: ai_model: meshy-n1 dikirim untuk preview yang di-remesh menjadi quad. Lakukan refine dengan ai_model lain.
- Terlalu banyak segitiga untuk Meshy N1: Dengan ai_model: meshy-n1, preview memiliki lebih dari 7.999.999 segitiga. Lakukan refine dengan ai_model lain.
- Opsi tidak didukung untuk Meshy N1: ai_model: meshy-n1 dikirim dengan salah satu opsi berikut:
  - texture_prompt
  - enable_pbr: true
  - texture_resolution berupa 4k atau 8k
  - hd_texture: true tanpa texture_resolution
  - remove_lighting: true
Perbaiki permintaan, lalu kirim lagi. Lihat Kesalahan.
Name
401 - Unauthorized
Description
Kunci API tidak ada atau tidak valid. Periksa header Authorization.
Name
402 - Payment Required
Description
Misalnya:
- Kredit tidak cukup: Akun tidak memiliki cukup kredit untuk tugas ini, atau akun telah mencapai batas kredit. Periksa saldo kredit Anda, lalu coba lagi.
- Paket gratis: Membuat tugas memerlukan paket berbayar. Tingkatkan paket Anda di pengaturan langganan, lalu coba lagi.
Name
403 - Forbidden
Description
Moderasi konten memblokir prompt atau gambar input. Ubah input, lalu coba lagi.
Name
429 - Too Many Requests
Description
Anda melebihi batas laju Anda. Tunggu, lalu coba lagi. Lihat Batas laju.

GET/openapi/v2/text-to-3d/:id

Dapatkan task Teks ke 3D

Mengembalikan task Teks ke 3D berdasarkan ID-nya. Ini berlaku untuk task preview maupun refine.

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": null,

  "consumed_credits": 20
}

Parameter

Name
id
Type
path
Description
ID task dari respons pembuatan (create).

Return

Objek task Teks ke 3D.

Contoh

Tabel berikut menunjukkan contoh model untuk setiap mode.

Mode	Contoh model
Preview
Refine

DELETE/openapi/v2/text-to-3d/:id

Hapus task Text to 3D

Menghapus task Teks ke 3D secara permanen, termasuk model dan datanya. Anda tidak dapat membatalkan penghapusan.

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 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."
}

Parameter path

Name
id
Type
path
Description
ID task yang akan dihapus.

Status task

Menghapus task PENDING akan mengembalikan kredit yang digunakan saat Anda membuatnya.

Task IN_PROGRESS tidak dapat dihapus. Permintaan akan mengembalikan 409 Conflict, dan task tetap berjalan. Meshy tidak mengembalikan kredit untuk task yang sudah dimulai, jadi menghapusnya akan membuat Anda rugi kredit sekaligus hasilnya. Tunggu hingga task mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

Menghapus task dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak mengembalikan kreditnya.

Pengembalian

200 OK ketika task berhasil dihapus, atau 409 Conflict ketika task sedang IN_PROGRESS.

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

Daftar tugas Teks ke 3D

Mengembalikan daftar tugas Teks ke 3D Anda.

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": null,

    "consumed_credits": 20
  }
]

Parameter

Name
page_num
Type
integer
default 1
Description
Nomor halaman yang akan dikembalikan, hingga 255. Nilai yang lebih besar akan mengembalikan 400.
Name
page_size
Type
integer
default 10
Description
Jumlah tugas per halaman, hingga 100.
Name
sort_by
Type
string
Description
Urutan pengurutan.
Nilai yang tersedia:
- +created_at: terlama lebih dulu
- -created_at: terbaru lebih dulu

Hasil

Daftar berhalaman dari objek tugas Teks ke 3D.

GET/openapi/v2/text-to-3d/:id/stream

Stream tugas Text to 3D

Melakukan streaming pembaruan tugas Text to 3D sebagai Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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": null,

"consumed_credits": 20
}

Parameter

Name
id
Type
path
Description
ID tugas dari respons pembuatan (create).

Returns

Sebuah stream dari objek tugas Text to 3D sebagai Server-Sent Events.

Setiap event menyimpan objek tugas secara utuh, dalam bentuk yang sama seperti yang dikembalikan oleh endpoint Get. Selama tugas berstatus PENDING atau IN_PROGRESS, kolom hasilnya belum memiliki nilai.

Objek tugas Text to 3D

Objek tugas Text to 3D menjelaskan satu tugas yang menghasilkan model 3D dari sebuah prompt teks. Objek ini menyimpan status, progress, dan file model ketika tugas berhasil. Teks ke 3D memiliki dua tahap, preview dan refine. Tugas preview menghasilkan model 3D berupa mesh saja, dan tugas refine menghasilkan model 3D bertekstur dari hasil preview.

Properties

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": null,

  "consumed_credits": 20
}

Name
id
Type
string
Description
ID tugas. Perlakukan sebagai string buram, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, text-to-3d-preview untuk tugas preview atau text-to-3d-refine untuk tugas refine.
Name
model_urls
Type
object
Description
URL unduhan untuk model 3D yang dihasilkan, satu per format file. Format yang tidak dihasilkan oleh tugas tidak memiliki kunci, bukan string kosong.
- Name
  glb
  Type
  string
  Description
  File GLB.
- Name
  fbx
  Type
  string
  Description
  File FBX.
- Name
  usdz
  Type
  string
  Description
  File USDZ.
- Name
  obj
  Type
  string
  Description
  File OBJ.
- Name
  mtl
  Type
  string
  Description
  File MTL.
- Name
  stl
  Type
  string
  Description
  File STL.
- Name
  3mf
  Type
  string
  Description
  File 3MF. Hanya ada ketika target_formats menyertakan 3mf.
Name
prompt
Type
string
Description
prompt yang Anda kirim untuk membuat tugas, tanpa perubahan.
Name
texture_prompt
Type
string
Description
Prompt teks yang Anda kirim untuk memandu pembuatan tekstur pada tahap refine.
Name
ultra_mode
Type
boolean
⚠ usang
Description
Gunakan geometry_resolution sebagai gantinya.
Name
geometry_resolution
Type
string
Description
Tingkatan Ultra yang digunakan tugas preview, 2k atau 4k. Kolom ini tidak ada untuk standard.
Name
texture_image_url
Type
string
Description
URL unduhan untuk gambar yang Anda kirim untuk memandu pembuatan tekstur.
Name
thumbnail_url
Type
string
Description
URL unduhan untuk gambar thumbnail dari model 3D.
Name
alpha_thumbnail_url
Type
string
Description
URL unduhan untuk versi thumbnail_url dengan latar belakang transparan (RGBA). Hanya ada ketika Anda membuat tugas dengan alpha_thumbnail: true dan Meshy me-render pratinjau transparan tersebut.
Name
progress
Type
integer
Description
Seberapa banyak tugas telah selesai, dalam persentase. Nilainya 0 sampai tugas dimulai dan 100 saat berhasil.
Name
started_at
Type
timestamp
Description
Waktu tugas dimulai, dalam milidetik Unix. Nilainya 0 sampai tugas dimulai.
Name
created_at
Type
timestamp
Description
Waktu tugas dibuat, dalam milidetik Unix.
Name
finished_at
Type
timestamp
Description
Waktu tugas selesai, dalam milidetik Unix. Nilainya 0 sampai tugas selesai.
Name
status
Type
string
Description
Status tugas, salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
texture_urls
Type
array
Description
URL unduhan untuk peta tekstur yang dihasilkan, sebagai array objek. Biasanya berisi satu objek. Setiap objek memiliki kolom berikut:
- Name
  base_color
  Type
  string
  Description
  Peta warna dasar.
- Name
  metallic
  Type
  string
  Description
  Peta metallic. Tidak ada ketika Anda membuat tugas dengan enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Peta normal. Tidak ada ketika Anda membuat tugas dengan enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Peta roughness. Tidak ada ketika Anda membuat tugas dengan enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Peta emission. Tidak ada pada salah satu kondisi berikut:
  
  Anda membuat tugas dengan enable_pbr: false.
  
  ai_model adalah meshy-6-lite, meshy-7, meshy-7.1, atau latest.
  
  texture_resolution adalah 8k.
  
  Tugas me-refine preview meshy-t2 atau meshy-t2.5 tanpa mengatur ai_model.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas di depan tugas ini dalam antrean. Nilai ini hanya bermakna selama tugas berstatus PENDING.
Name
task_error
Type
object
Description
Detail kesalahan ketika tugas gagal. Nilainya null kecuali statusnya FAILED. Lihat Kesalahan.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang digunakan tugas. Ada ketika statusnya PENDING, IN_PROGRESS, atau SUCCEEDED. Nilainya 0 untuk tugas FAILED, karena Meshy mengembalikan kredit ketika tugas gagal.