lowpoly akan dihentikan pada 30 Okt 2026. Tukar model sebelum tarikh-tarikh ini untuk mengelakkan ralat permintaan.

API Teks ke 3D

API Teks ke 3D ialah ciri yang membolehkan anda mengintegrasikan keupayaan Teks ke 3D Meshy ke dalam aplikasi anda sendiri. Dalam bahagian ini, anda akan menemui semua maklumat yang anda perlukan untuk bermula dengan API ini.

Teks ke 3D menggunakan aliran kerja dua langkah. Pertama, cipta tugas preview (mode: "preview") untuk menjana jejaring 3D tanpa tekstur, supaya anda boleh menilai bentuknya. Kemudian, hantar ID tugas preview yang telah selesai itu kepada tugas refine (mode: "refine") untuk mengenakan tekstur pada jejaring tersebut. Kedua-dua langkah ini berkongsi endpoint yang sama.

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

Create a Text to 3D Preview Task

Endpoint ini mencipta tugas pratonton Teks ke 3D, yang menjana jejaring 3D tanpa tekstur (geometri sahaja) daripada prompt teks. Ini adalah langkah pertama dalam aliran kerja dua langkah. Setelah pratonton berjaya, gunakan ID tugas yang dikembalikan untuk mencipta tugas refine bagi tujuan pemberian tekstur. Rujuk Objek Tugas Teks ke 3D untuk skema respons lengkap.

Tugas berjalan di latar belakang. Untuk tempoh masa yang biasanya diperlukan, lihat Masa Pemprosesan.

Parameter

  • Name
    mode
    Type
    string
    Diperlukan
    Description

    Medan ini perlu ditetapkan kepada "preview" apabila mencipta tugas pratonton.

  • Name
    prompt
    Type
    string
    Diperlukan
    Description

    Terangkan jenis objek yang diwakili oleh model 3D tersebut. Maksimum 800 aksara.

  • Name
    model_type
    Type
    string
    lalai standard
    Description

    Tentukan jenis penjanaan jejaring 3D.

    Nilai yang tersedia:

    • standard: Penjanaan jejaring 3D berperincian tinggi biasa.
    • smart-topology: Pilih model Smart Topology dengan ai_model (meshy-t2 atau meshy-t2.5).
    • lowpoly (lapuk, akan dipersarakan pada 30 Oktober 2026): Menjana jejaring low-poly yang dioptimumkan untuk poligon yang lebih kemas. Kami mengesyorkan Meshy T2.5 sebagai gantinya: smart-topology dengan meshy-t2.5.

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

    lowpoly akan dipersarakan pada 30 Oktober 2026. Selepas tarikh tersebut, permintaan dengan model_type: "lowpoly" akan mengembalikan ralat. Kami mengesyorkan beralih kepada Meshy T2.5 (model_type: "smart-topology" dengan ai_model: "meshy-t2.5"). Apabila lowpoly dipilih, ai_model, topology, target_polycount, dan should_remesh diabaikan.

  • Name
    ai_model
    Type
    string
    lalai latest
    Description

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

    Penjanaan standard (model_type: standard):

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

    Penjanaan Smart Topology (model_type: smart-topology):

    • meshy-t2: model Smart Topology — topology yang lebih kemas, bahagian yang dipisahkan secara semula jadi, output segi tiga, dan bilangan muka yang boleh ditetapkan dengan target_polycount.
    • meshy-t2.5 (lalai): Perincian lebih tajam untuk aset permainan. Output segi tiga, dan bilangan muka yang boleh ditetapkan dengan target_polycount.
  • Name
    geometry_resolution
    Type
    string
    lalai standard
    Description

    Laluan penjanaan geometri. 2k menjalankan laluan Ultra pada 2048³; 4k menjalankannya pada 4096³ untuk perincian permukaan paling halus.

    Nilai yang tersedia: standard, 2k, 4k

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

  • Name
    ultra_mode
    Type
    boolean
    ⚠ lapuk
    lalai false
    Description

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

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

    Mengawal sama ada untuk mendayakan fasa remesh. Untuk model berkualiti tertinggi, kami mengesyorkan menetapkan should_remesh kepada false.

Hanya berlaku apabila should_remesh = true
  • Name
    topology
    Type
    string
    lalai triangle
    Description

    Tentukan topology model yang dijana.

    Nilai yang tersedia:

    • quad: Menjana jejaring yang didominasi segi empat (quad).
    • triangle: Menjana jejaring segi tiga yang telah dinyahkan (decimated).

    Output Smart Topology adalah segi tiga sahaja. Meminta quad bersama ai_model meshy-t2 atau meshy-t2.5 akan mengembalikan ralat.

  • Name
    decimation_mode
    Type
    integer
    Description

    Dayakan decimation adaptif dengan menetapkan tahap bilangan poligon. Apabila ditetapkan, target_polycount diabaikan.

    Nilai yang tersedia:

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

    Sasaran bilangan poligon (muka) dalam output. Bilangan sebenar mungkin berbeza daripada sasaran bergantung pada geometri.

    target_polycount berkuat kuasa dalam dua keadaan bebas:

    • Remesh — dengan should_remesh: true pada model standard. Jejaring tersebut akan di-remesh (dinyahkan) kepada kira-kira bilangan ini. Julat 100 hingga 300,000, lalai 30,000. Jika decimation_mode ditetapkan, ia mengambil keutamaan dan target_polycount diabaikan.
    • Smart Topology — dengan model_type: smart-topology dan ai_model meshy-t2 atau meshy-t2.5. Model dijana terus pada bilangan muka ini; tiada remesh dijalankan dan should_remesh tidak diperlukan. Untuk meshy-t2: julat 100 hingga 15,000, lalai 4,000. Untuk meshy-t2.5: julat 100 hingga 30,000, lalai 15,000.
  • Name
    symmetry_mode
    Type
    string
    ⚠ lapuk
    lalai auto
    Description

    Lapuk. Parameter ini tidak lagi memberi kesan kepada output.

    Medan symmetry_mode mengawal tingkah laku simetri semasa proses penjanaan model.

    Nilai yang sah ialah:

    • off: Melumpuhkan simetri.
    • auto: Secara automatik menentukan dan menerapkan simetri berdasarkan geometri input.
    • on: Menguatkuasakan simetri semasa penjanaan.
  • Name
    pose_mode
    Type
    string
    lalai ""
    Description

    Tentukan mode pose untuk model yang dijana.

    Nilai yang tersedia:

    • a-pose: Menjana model dalam pose A.
    • t-pose: Menjana model dalam pose T.
    • "" (rentetan kosong): Tiada pose khusus diterapkan.
  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ lapuk
    lalai false
    Description

    Gunakan pose_mode sebagai gantinya. Sama ada untuk menjana model dalam pose A/T.

  • Name
    art_style
    Type
    string
    ⚠ lapuk
    lalai realistic
    Description

    Tidak disokong oleh Meshy-6. Permintaan menggunakan Meshy-6 akan mengabaikan art_style, dan sesetengah kombinasi mungkin menyebabkan ralat. Nilai yang tersedia: realistic, sculpture.

    enable_pbr perlu ditetapkan kepada false apabila menggunakan gaya Sculpture, kerana gaya Sculpture menjana set peta PBR tersendiri.

  • Name
    moderation
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, kandungan input akan disaring secara automatik untuk kandungan yang berpotensi berbahaya. Jika kandungan berbahaya dikesan, tugas tidak akan diteruskan kepada penjanaan.

    Teks daripada prompt akan disaring.

  • Name
    target_formats
    Type
    string[]
    Description

    Menentukan format fail 3D yang hendak disertakan dalam output. Hanya format yang diminta akan dijana dan dikembalikan, yang boleh mengurangkan masa penyelesaian tugas. Apabila ditinggalkan, semua format yang disokong akan disertakan.

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

    Apabila ditinggalkan, semua format kecuali 3mf akan dijana. 3mf hanya disertakan apabila dinyatakan secara eksplisit.

  • Name
    alpha_thumbnail
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, tugas tersebut turut merender versi latar belakang lutsinar (RGBA) bagi pratonton dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Medan thumbnail_url sedia ada tidak berubah.

  • Name
    auto_size
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, perkhidmatan menggunakan penglihatan AI untuk menganggarkan secara automatik ketinggian sebenar objek tersebut dan mengubah saiz model mengikutnya. Titik asal akan menjadi bottom secara lalai melainkan origin_at ditetapkan secara eksplisit.

Hanya berlaku apabila auto_size = true
  • Name
    origin_at
    Type
    string
    lalai bottom
    Description

    Kedudukan titik asal apabila auto_size didayakan.

    Nilai yang tersedia: bottom, center.

Pulangan

Sifat result bagi respons mengandungi id tugas bagi tugas Teks ke 3D yang baru dicipta.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Punca biasa:

    • Parameter hilang: Parameter yang diperlukan (contohnya, prompt, mode) tiada.
    • Parameter tidak sah: art_style bukan salah satu daripada nilai yang dibenarkan.
    • Prompt terlalu panjang: prompt melebihi had aksara.
    • Model tidak disokong untuk low poly: ai_model: "meshy-6-lite" tidak menyokong model_type: "lowpoly".
    • Model tidak disokong untuk Ultra: geometry_resolution memerlukan meshy-7.1 atau latest.
  • Name
    401 - Unauthorized
    Description

    Pengesahan gagal. Sila semak kunci API anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melaksanakan tugas ini.

  • Name
    429 - Too Many Requests
    Description

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

Create a Text to 3D Refine Task

Endpoint ini mencipta tugasan Teks ke 3D refine, yang mengenakan tekstur pada jejaring preview yang telah selesai. Anda perlu menyediakan preview_task_id daripada tugasan preview yang berjaya. Ini ialah langkah kedua dalam aliran kerja dua langkah.

Tugasan ini berjalan di latar belakang. Untuk tempoh yang biasanya diambil, lihat Processing Times.

Parameter

  • Name
    mode
    Type
    string
    Diperlukan
    Description

    Medan ini perlu ditetapkan kepada "refine" apabila mencipta tugasan refine.

  • Name
    preview_task_id
    Type
    string
    Diperlukan
    Description

    ID tugasan preview yang berkaitan.

    Status tugasan preview yang diberikan mestilah SUCCEEDED.

  • Name
    enable_pbr
    Type
    boolean
    lalai false
    Description

    Jana peta PBR (metallic, roughness, normal) selain daripada warna asas. Peta emission turut disertakan apabila ai_model ialah meshy-6, kecuali pada texture_resolution: 8k (tiada peta emission dihasilkan). meshy-6-lite, meshy-7.1 dan latest tidak menghasilkan peta emission, begitu juga refine bagi preview meshy-t2 yang tidak menetapkan ai_model.

  • Name
    texture_resolution
    Type
    string
    lalai 2k
    Description

    Resolusi tekstur warna asas. Salah satu daripada 2k (2048×2048), 4k (4096×4096), atau 8k (8192×8192). Resolusi yang lebih tinggi menangkap lebih banyak perincian permukaan. Hanya terpakai untuk mode refine.

    4k dan 8k memerlukan ai_model meshy-6, meshy-7.1, atau latest. Pada 8k, tiada peta emission dihasilkan.

  • Name
    hd_texture
    Type
    boolean
    ⚠ lapuk
    lalai false
    Description

    Gunakan texture_resolution sebagai gantinya — setara dengan texture_resolution: "4k". Apabila kedua-duanya ditetapkan, texture_resolution diutamakan.

  • Name
    texture_prompt
    Type
    string
    Description

    Berikan prompt teks tambahan untuk memandu proses pemberian tekstur. Maksimum 800 aksara.

  • Name
    texture_image_url
    Type
    string
    Description

    Berikan imej 2D untuk memandu proses pemberian tekstur. Kami kini menyokong format .jpg, .jpeg, .png, dan .webp.

    Saiz fail maksimum: 20 MB.

    Terdapat dua cara untuk menyediakan imej tersebut:

    • URL yang boleh diakses secara awam: URL yang boleh diakses daripada internet awam
    • Data URI: Data URI imej yang dikodkan base64. Contoh data URI: data:image/jpeg;base64,<your base64-encoded image data>

    Pemberian tekstur imej mungkin tidak berfungsi dengan optimum jika terdapat perbezaan geometri yang ketara antara aset asal dan imej yang dimuat naik. Hanya salah satu daripada texture_image_url atau texture_prompt boleh digunakan untuk memandu proses pemberian tekstur. Jika kedua-dua parameter disediakan, maka texture_prompt akan digunakan secara lalai untuk memberi tekstur pada model tersebut.

  • Name
    ai_model
    Type
    string
    lalai 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 (lapuk): gunakan meshy-7.1 sebagai gantinya.

    Biarkan parameter ini tanpa nilai untuk mewarisi model yang digunakan oleh tugasan preview, yang mengekalkan preview dan refine-nya pada model yang sama dari hujung ke hujung. Berikan nilai yang eksplisit untuk mengatasi pewarisan tersebut.

    latest yang eksplisit diselesaikan di sini dengan cara yang sama seperti pada tugasan preview (pada masa ini Meshy 7.1), jadi preview latest dan refine latest-nya sentiasa jatuh pada model tekstur yang sama.

  • Name
    moderation
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, kandungan input akan disaring secara automatik untuk kandungan yang berpotensi berbahaya. Jika kandungan berbahaya dikesan, tugasan tidak akan diteruskan ke penjanaan.

    Kedua-dua teks daripada texture_prompt dan imej daripada texture_image_url akan disaring.

  • Name
    remove_lighting
    Type
    boolean
    lalai true
    Description

    Membuang sorotan (highlights) dan bayang-bayang daripada tekstur warna asas, menghasilkan keputusan yang lebih bersih yang berfungsi dengan lebih baik di bawah persediaan pencahayaan tersuai.

    Hanya berkesan apabila ai_model ialah meshy-6. meshy-7.1 dan latest menerima parameter ini tetapi mengabaikannya, begitu juga refine bagi preview meshy-t2 yang tidak menetapkan ai_model. Menetapkannya dengan meshy-6-lite akan mengembalikan ralat.

  • Name
    target_formats
    Type
    string[]
    Description

    Menentukan format fail 3D yang hendak disertakan dalam output. Hanya format yang diminta akan dijana dan dikembalikan, yang boleh mengurangkan masa penyiapan tugasan. Apabila ditinggalkan, semua format yang disokong akan disertakan.

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

    Apabila ditinggalkan, semua format kecuali 3mf akan dijana. 3mf hanya disertakan apabila dinyatakan secara eksplisit.

  • Name
    alpha_thumbnail
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, tugasan ini tambahan pula merender versi latar belakang lutsinar (RGBA) bagi preview dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Medan thumbnail_url yang sedia ada tidak berubah.

  • Name
    auto_size
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, perkhidmatan ini menggunakan penglihatan AI untuk menganggarkan secara automatik ketinggian objek di dunia sebenar dan mengubah saiz model sewajarnya. Titik asal akan menjadi bottom secara lalai melainkan origin_at ditetapkan secara eksplisit.

Hanya berlaku apabila auto_size = true
  • Name
    origin_at
    Type
    string
    lalai bottom
    Description

    Kedudukan titik asal apabila auto_size didayakan.

    Nilai yang tersedia: bottom, center.

Returns

Ciri result bagi respons mengandungi id tugasan bagi tugasan Teks ke 3D yang baru dicipta.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Punca biasa:

    • ID tugasan tidak sah: preview_task_id tidak sah atau tidak wujud.
    • Tugasan belum sedia: Tugasan preview belum lagi berjaya.
    • Ketidakpadanan model: Model AI bagi tugasan preview tidak serasi dengan model refine yang diminta.
    • Model tidak disokong untuk remove_lighting: remove_lighting ditetapkan dengan ai_model: "meshy-6-lite".
  • Name
    401 - Unauthorized
    Description

    Pengesahan gagal. Sila semak kunci API anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melaksanakan tugasan ini.

  • Name
    404 - Not Found
    Description

    Tugasan preview yang dinyatakan oleh preview_task_id tidak ditemui.

  • Name
    429 - Too Many Requests
    Description

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

Dapatkan Semula Tugas Teks ke 3D

Endpoint ini membolehkan anda mendapatkan semula tugas Teks ke 3D dengan memberikan id tugas yang sah. Rujuk Objek Tugas Teks ke 3D untuk melihat sifat-sifat yang disertakan dalam objek tugas Teks ke 3D.

Endpoint ini berfungsi untuk kedua-dua tugas preview dan refine.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugas Teks ke 3D yang hendak didapatkan semula.

Pulangan

Respons mengandungi objek tugas Teks ke 3D. Semak bahagian Objek Tugas Teks ke 3D untuk maklumat lanjut.

Contoh

ModeModel Contoh
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

Padam Tugasan Teks ke 3D

Endpoint ini memadam secara kekal satu tugasan Teks ke 3D, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh dibatalkan.

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    ID tugasan Teks ke 3D yang hendak dipadam.

Status Tugasan

Tugasan yang masih PENDING akan dipadam dan kredit yang digunakan semasa penciptaan akan dikembalikan.

Tugasan yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugasan akan terus berjalan. Kredit bagi tugasan yang sudah mula diproses oleh worker tidak boleh dikembalikan, jadi memadamnya semasa ia sedang berjalan akan menyebabkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugasan yang berada dalam status akhir (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa sebarang pemulangan kredit.

Pulangan

Mengembalikan 200 OK apabila berjaya, atau 409 Conflict apabila tugasan masih 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 membolehkan anda mendapatkan semula senarai tugas Teks ke 3D.

Parameter

  • Name
    page_num
    Type
    integer
    lalai 1
    Description

    Nombor halaman untuk penomboran halaman.

  • Name
    page_size
    Type
    integer
    lalai 10
    Description

    Had saiz halaman. Maksimum yang dibenarkan ialah 100 item.

  • Name
    sort_by
    Type
    string
    Description

    Medan untuk disusun mengikut.

    Nilai yang tersedia:

    • +created_at: Susun mengikut masa penciptaan secara menaik.
    • -created_at: Susun mengikut masa penciptaan secara menurun.

Returns

Mengembalikan senarai berpenomboran halaman bagi 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 Tugas Teks ke 3D

Endpoint ini menstream kemas kini masa nyata untuk tugas Teks ke 3D menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugas Teks ke 3D yang hendak distream.

Pulangan

Mengembalikan aliran Objek Tugas Teks ke 3D sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan mengandungi medan 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 Tugas Teks ke 3D ialah unit kerja yang dijejaki oleh Meshy untuk menjana model 3D daripada input teks. Terdapat dua peringkat bagi API Teks ke 3D, preview dan refine. Peringkat preview adalah untuk menjana model 3D jejaring sahaja, dan peringkat refine adalah untuk menjana model 3D bertekstur berdasarkan hasil peringkat preview.

Objek ini mempunyai sifat-sifat berikut:

Sifat-sifat

  • Name
    id
    Type
    string
    Description

    Pengenal unik untuk tugas tersebut. Walaupun kami menggunakan UUID yang boleh disusun secara k (k-sortable UUID) sebagai butiran pelaksanaan untuk id tugas, anda tidak sepatutnya membuat sebarang andaian tentang format id tersebut.

  • Name
    type
    Type
    string
    Description

    Jenis tugas Teks ke 3D. Nilai yang mungkin ialah text-to-3d-preview untuk tugas peringkat preview dan text-to-3d-refine untuk tugas peringkat refine.

  • Name
    model_urls
    Type
    object
    Description

    URL yang boleh dimuat turun untuk fail model 3D bertekstur yang dijana oleh Meshy. Sifat untuk sesuatu format akan ditinggalkan jika format tersebut tidak dijana, dan bukannya memulangkan rentetan kosong.

    • Name
      glb
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail GLB.

    • Name
      fbx
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail FBX.

    • Name
      usdz
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail USDZ.

    • Name
      obj
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail OBJ.

    • Name
      mtl
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail MTL.

    • Name
      stl
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail STL.

    • Name
      3mf
      Type
      string
      Description

      URL yang boleh dimuat turun untuk fail 3MF. Hanya hadir apabila 3mf diminta melalui target_formats.

  • Name
    prompt
    Type
    string
    Description

    Ini ialah prompt yang tidak diubah suai yang digunakan untuk mencipta tugas tersebut.

  • Name
    negative_prompt
    Type
    string
    ⚠ lapuk
    Description

    Dikekalkan untuk keserasian ke belakang. Medan ini tidak mempunyai sebarang kesan fungsian terhadap model yang dijana.

  • Name
    art_style
    Type
    string
    ⚠ lapuk
    Description

    art_style yang tidak diubah suai yang digunakan untuk mencipta tugas preview. Tidak disokong oleh Meshy-6.

  • Name
    texture_richness
    Type
    string
    ⚠ lapuk
    Description

    Dikekalkan untuk keserasian ke belakang. Medan ini tidak mempunyai sebarang kesan fungsian terhadap model yang dijana.

  • Name
    texture_prompt
    Type
    string
    Description

    Prompt teks tambahan yang disediakan untuk membimbing proses tekstur semasa peringkat refine.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ lapuk
    Description

    Lapuk; sila baca geometry_resolution sebaliknya.

  • Name
    geometry_resolution
    Type
    string
    Description

    Tingkat Ultra yang digunakan oleh tugas preview (2k atau 4k); ditinggalkan untuk standard.

  • Name
    texture_image_url
    Type
    string
    Description

    URL yang boleh dimuat turun untuk imej tekstur yang digunakan untuk membimbing proses tekstur.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL yang boleh dimuat turun untuk imej kecil bagi fail model.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL yang boleh dimuat turun untuk versi latar belakang telus (RGBA) bagi thumbnail_url. Hanya hadir apabila tugas dicipta dengan alpha_thumbnail: true dan pratonton telus berjaya dihasilkan; jika tidak, medan ini akan ditinggalkan.

  • Name
    video_url
    Type
    string
    ⚠ lapuk
    Description

    URL yang boleh dimuat turun untuk video pratonton. Akan dibuang dalam keluaran akan datang.

  • Name
    progress
    Type
    integer
    Description

    Kemajuan tugas. Jika tugas belum bermula lagi, sifat ini akan menjadi 0. Setelah tugas berjaya, nilai ini akan menjadi 100.

  • Name
    started_at
    Type
    timestamp
    Description

    Cap masa menunjukkan bila tugas dimulakan, dalam milisaat. Jika tugas belum bermula lagi, sifat ini akan menjadi 0.

    Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut piawaian RFC 3339. Sebagai contoh, Jumaat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini terpakai kepada semua cap masa dalam Meshy API.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa menunjukkan bila tugas dicipta, dalam milisaat.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa menunjukkan bila tugas selesai, dalam milisaat. Jika tugas belum selesai lagi, sifat ini akan menjadi 0.

  • Name
    status
    Type
    string
    Description

    Status tugas. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    texture_urls
    Type
    array
    Description

    Satu tatasusunan objek URL tekstur yang dijana daripada tugas tersebut. Biasanya ini hanya mengandungi satu objek URL tekstur. Setiap URL tekstur mempunyai sifat-sifat berikut:

    • Name
      base_color
      Type
      string
      Description

      URL yang boleh dimuat turun untuk imej peta warna asas.

    • Name
      metallic
      Type
      string
      Description

      URL yang boleh dimuat turun untuk imej peta logam (metallic).

      Jika tugas dicipta dengan enable_pbr: false, sifat ini akan ditinggalkan.

    • Name
      normal
      Type
      string
      Description

      URL yang boleh dimuat turun untuk imej peta normal.

      Jika tugas dicipta dengan enable_pbr: false, sifat ini akan ditinggalkan.

    • Name
      roughness
      Type
      string
      Description

      URL yang boleh dimuat turun untuk imej peta kekasaran.

      Jika tugas dicipta dengan enable_pbr: false, sifat ini akan ditinggalkan.

    • Name
      emission
      Type
      string
      Description

      URL yang boleh dimuat turun untuk imej peta pancaran (emission).

      Jika tugas dicipta dengan enable_pbr: false, jika ai_model ialah meshy-6-lite, meshy-7.1, atau latest, atau jika tugas tersebut melakukan refine terhadap preview meshy-t2 tanpa menetapkan ai_model, sifat ini akan ditinggalkan.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugas terdahulu.

    Nilai medan ini hanya bermakna jika status tugas ialah PENDING.

  • Name
    task_error
    Type
    object
    Description

    Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bilangan kredit yang digunakan oleh tugas ini. Hadir apabila status tugas ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Memulangkan 0 untuk tugas FAILED (kredit dikembalikan apabila 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
}