Text to 3D API

Ang Text to 3D API ay isang feature na nagbibigay-daan sa iyo upang isama ang kakayahan ng Meshy sa Text to 3D sa iyong sariling application. Sa seksyong ito, makikita mo ang lahat ng impormasyong kinakailangan mo upang makapagsimula sa API na ito.

Ginagamit ng Text to 3D ang dalawang-hakbang na workflow. Una, gumawa ng preview task (mode: "preview") upang makabuo ng 3D mesh na walang texture, para masuri mo ang hugis. Pagkatapos, ipasa ang task ID ng nakumpletong preview sa isang refine task (mode: "refine") upang ilapat ang texture sa mesh. Pareho ang endpoint na ginagamit ng dalawang hakbang na ito.

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

Create a Text to 3D Preview Task

Ang endpoint na ito ay lumilikha ng Text to 3D preview task, na bumubuo ng isang walang texture na 3D mesh (heometriya lamang) mula sa isang text prompt. Ito ang unang hakbang sa dalawang-hakbang na workflow. Kapag matagumpay na ang preview, gamitin ang naibalik na task ID upang gumawa ng refine task para sa texturing. Sumangguni sa The Text to 3D Task Object para sa buong response schema.

Mga Parameter

  • Name
    mode
    Type
    string
    Kinakailangan
    Description

    Dapat itakda ang field na ito sa "preview" kapag gumagawa ng preview task.

  • Name
    prompt
    Type
    string
    Kinakailangan
    Description

    Ilarawan kung anong uri ng bagay ang 3D model. Maximum na 800 na character.

  • Name
    model_type
    Type
    string
    default standard
    Description

    Tukuyin ang uri ng 3D mesh generation.

    Mga available na value:

    • standard: Regular na high-detail na 3D mesh generation.
    • smart-topology: Piliin ang Smart Topology model gamit ang ai_model (meshy-t2).
    • lowpoly (deprecated): Bumubuo ng low-poly mesh na na-optimize para sa mas malinis na polygons. Inirerekomenda naming gamitin ang smart-topology sa halip.

    Kapag napili ang smart-topology, hindi pinapansin ang should_remesh at decimation_mode, at topology: triangle lang ang tinatanggap.

    Kapag napili ang lowpoly, hindi pinapansin ang ai_model, topology, target_polycount, at should_remesh.

  • Name
    ai_model
    Type
    string
    default latest
    Description

    ID ng model na gagamitin. Ang mga available na value ay depende sa model_type.

    Standard generation (model_type: standard):

    • meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
    • meshy-7 (deprecated): gamitin ang meshy-7.1 sa halip.

    Smart Topology generation (model_type: smart-topology):

    • meshy-t2 (default): ang Smart Topology model — mas malinis na topology, likas na hiwalay na mga bahagi, triangle output, at isang bilang ng face na maaari mong itakda gamit ang target_polycount.
  • Name
    geometry_resolution
    Type
    string
    default standard
    Description

    Geometry generation pass. Pinapatakbo ng 2k ang Ultra pass sa 2048³; pinapatakbo ito ng 4k sa 4096³ para sa pinakamainam na detalye ng ibabaw.

    Mga available na value: standard, 2k, 4k

    Sinusuportahan lamang sa preview mode. Kailangan ang meshy-7.1 o latest.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ lipas na
    default false
    Description

    Gamitin ang geometry_resolution sa halip. Ang ultra_mode: true ay katumbas ng geometry_resolution: "2k".

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

    Kinokontrol kung papagana ang remesh phase. Para sa pinakamataas na kalidad ng model, inirerekomenda naming itakda ang should_remesh sa false.

Naaangkop lamang kapag should_remesh = true
  • Name
    topology
    Type
    string
    default triangle
    Description

    Tukuyin ang topology ng nabuong model.

    Mga available na value:

    • quad: Bumuo ng quad-dominant na mesh.
    • triangle: Bumuo ng decimated na triangle mesh.

    Ang output ng Smart Topology ay triangle lamang. Kapag hiniling ang quad kasabay ng ai_model: meshy-t2, magbabalik ito ng error.

  • Name
    decimation_mode
    Type
    integer
    Description

    Paganahin ang adaptive decimation sa pamamagitan ng pagtakda ng antas ng polycount. Kapag itinakda, hindi pinapansin ang target_polycount.

    Mga available na value:

    • 1: Adaptive — ultra polycount.
    • 2: Adaptive — mataas na polycount.
    • 3: Adaptive — katamtamang polycount.
    • 4: Adaptive — mababang polycount.
  • Name
    target_polycount
    Type
    integer
    Description

    Target na bilang ng polygons (faces) sa output. Maaaring iba ang aktwal na bilang mula sa target depende sa heometriya.

    Nagkakabisa ang target_polycount sa dalawang hiwalay na kaso:

    • Remesh — kasama ang should_remesh: true sa isang standard na model. Ang mesh ay ni-remesh (decimated) sa humigit-kumulang na bilang na ito. Saklaw na 100 hanggang 300,000, default na 30,000. Kung itinakda ang decimation_mode, ito ang mangunguna at hindi papansinin ang target_polycount.
    • Smart Topology — kasama ang model_type: smart-topology at ai_model: meshy-t2. Direktang binubuo ang model sa bilang ng face na ito; walang tumatakbong remesh at hindi kailangan ang should_remesh. Saklaw na 100 hanggang 15,000, default na 4,000.
  • Name
    symmetry_mode
    Type
    string
    ⚠ lipas na
    default auto
    Description

    Deprecated na. Hindi na apektado ng parameter na ito ang output.

    Kinokontrol ng field na symmetry_mode ang asal ng simetriya sa panahon ng proseso ng pagbuo ng model.

    Ang mga wastong value ay:

    • off: Ini-disable ang simetriya.
    • auto: Awtomatikong tinutukoy at inilalapat ang simetriya batay sa input na heometriya.
    • on: Ipinapatupad ang simetriya sa panahon ng generation.
  • Name
    pose_mode
    Type
    string
    default ""
    Description

    Tukuyin ang pose mode para sa nabuong model.

    Mga available na value:

    • a-pose: Buuin ang model sa A pose.
    • t-pose: Buuin ang model sa T pose.
    • "" (empty string): Walang partikular na pose na inilapat.
  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ lipas na
    default false
    Description

    Gamitin ang pose_mode sa halip. Kung bubuuin ang model sa A/T pose.

  • Name
    art_style
    Type
    string
    ⚠ lipas na
    default realistic
    Description

    Hindi sinusuportahan ng Meshy-6. Hindi papansinin ng mga request na gumagamit ng Meshy-6 ang art_style, at maaaring magdulot ng error ang ilang kumbinasyon. Mga available na value: realistic, sculpture.

    Dapat itakda ang enable_pbr sa false kapag ginagamit ang Sculpture style, dahil bumubuo ang Sculpture style ng sarili nitong set ng PBR maps.

  • Name
    moderation
    Type
    boolean
    default false
    Description

    Kapag itinakda sa true, awtomatikong sisiyasatin ang input content para sa potensyal na nakakapinsalang nilalaman. Kung may natukoy na nakakapinsalang nilalaman, hindi magpapatuloy ang task sa generation.

    Ang teksto mula sa prompt ang sisiyasatin.

  • Name
    target_formats
    Type
    string[]
    Description

    Tinutukoy kung aling mga 3D file format ang isasama sa output. Ang mga hiniling na format lamang ang bubuuin at ibabalik, na maaaring magpababa sa oras ng pagkumpleto ng task. Kapag hindi isinama, lahat ng suportadong format ay kasama.

    Mga available na value: glb, obj, fbx, stl, usdz, 3mf

    Kapag hindi isinama, lahat ng format maliban sa 3mf ang bubuuin. Ang 3mf ay isasama lamang kapag tahasang tinukoy.

  • Name
    alpha_thumbnail
    Type
    boolean
    default false
    Description

    Kapag itinakda sa true, karagdagang bubuo ang task ng bersyon na may transparent background (RGBA) ng preview at ibabalik ito bilang alpha_thumbnail_url sa GET response. Hindi nagbabago ang umiiral nang field na thumbnail_url.

  • Name
    auto_size
    Type
    boolean
    default false
    Description

    Kapag itinakda sa true, gagamitin ng serbisyo ang AI vision upang awtomatikong tantiyahin ang tunay na taas ng bagay sa totoong mundo at i-resize ang model nang naaayon. Ang origin ay magiging bottom bilang default maliban kung tahasang itinakda ang origin_at.

Naaangkop lamang kapag auto_size = true
  • Name
    origin_at
    Type
    string
    default bottom
    Description

    Posisyon ng origin kapag pinagana ang auto_size.

    Mga available na value: bottom, center.

Mga Ibabalik

Ang property na result ng response ay naglalaman ng task id ng bagong nagawang Text to 3D task.

Mga Mode ng Kabiguan

  • Name
    400 - Bad Request
    Description

    Hindi katanggap-tanggap ang request. Karaniwang mga dahilan:

    • Nawawalang parameter: Nawawala ang isang kinakailangang parameter (hal., prompt, mode).
    • Di-wastong parameter: Ang art_style ay hindi isa sa mga pinapayagang value.
    • Masyadong mahaba ang prompt: Lumampas ang prompt sa limitasyon ng character.
    • Hindi sinusuportahang model para sa low poly: Hindi sinusuportahan ng ai_model: "meshy-6-lite" ang model_type: "lowpoly".
    • Hindi sinusuportahang model para sa Ultra: Kailangan ng geometry_resolution ang meshy-7.1 o latest.
  • Name
    401 - Unauthorized
    Description

    Nabigo ang authentication. Pakisuri ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Hindi sapat na credits upang isagawa ang task na ito.

  • Name
    429 - Too Many Requests
    Description

    Nalampasan mo ang iyong rate limit.

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

Ang endpoint na ito ay lumilikha ng Text to 3D refine task, na naglalapat ng texture sa isang kumpletong preview mesh. Kailangan mong ibigay ang preview_task_id mula sa isang matagumpay na preview task. Ito ang ikalawang hakbang sa dalawang-hakbang na workflow.

Mga Parameter

  • Name
    mode
    Type
    string
    Kinakailangan
    Description

    Dapat itakda ang field na ito sa "refine" kapag gumagawa ng refine task.

  • Name
    preview_task_id
    Type
    string
    Kinakailangan
    Description

    Ang kaukulang preview task id.

    Ang status ng ibinigay na preview task ay dapat SUCCEEDED.

  • Name
    enable_pbr
    Type
    boolean
    default false
    Description

    Lumikha ng PBR maps (metallic, roughness, normal) bilang dagdag sa base color. Isasama rin ang emission map kapag ang ai_model ay meshy-6, maliban sa texture_resolution: 8k (walang lilikhang emission map). Ang meshy-6-lite, meshy-7.1, at latest ay hindi lumilikha ng emission map.

  • Name
    texture_resolution
    Type
    string
    default 2k
    Description

    Ang resolution ng base color texture. Isa sa 2k (2048×2048), 4k (4096×4096), o 8k (8192×8192). Ang mas mataas na resolution ay nakakakuha ng mas maraming detalye sa ibabaw. Nalalapat lamang sa refine mode.

    Ang 4k at 8k ay nangangailangan ng ai_model na meshy-6, meshy-7.1, o latest. Sa 8k, walang lilikhang emission map.

  • Name
    hd_texture
    Type
    boolean
    ⚠ lipas na
    default false
    Description

    Gamitin ang texture_resolution sa halip — katumbas ng texture_resolution: "4k". Kapag naitakda ang dalawa, ang texture_resolution ang mananaig.

  • Name
    texture_prompt
    Type
    string
    Description

    Magbigay ng karagdagang text prompt para gabayan ang proseso ng texturing. Pinakamataas na 800 characters.

  • Name
    texture_image_url
    Type
    string
    Description

    Magbigay ng 2d na larawan para gabayan ang proseso ng texturing. Kasalukuyang suportado namin ang mga format na .jpg, .jpeg, at .png.

    May dalawang paraan para magbigay ng larawan:

    • Publicly accessible URL: Isang URL na accessible mula sa publikong internet
    • Data URI: Isang base64-encoded data URI ng larawan. Halimbawa ng data URI: data:image/jpeg;base64,<your base64-encoded image data>

    Ang image texturing ay maaaring hindi gumana nang optimal kung mayroong malaking pagkakaiba sa heometriya sa pagitan ng orihinal na asset at ang na-upload na larawan. Isa lamang sa texture_image_url o texture_prompt ang maaaring gamitin para gabayan ang proseso ng texturing. Kung ibinigay ang dalawang parameter, ang texture_prompt ang gagamitin bilang default para i-texture ang modelo.

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

    ID ng modelong gagamitin para sa refining.

    Mga available na value:

    • meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
    • meshy-7 (deprecated): gamitin ang meshy-7.1 sa halip.

    Huwag isama ang parameter na ito para mana ang modelong ginamit ng preview task, na pinananatiling parehong modelo ang preview at ang refine nito mula umpisa hanggang katapusan. Magpasa ng explicit na value para i-override ang pagmana na ito.

    Ang isang explicit na latest ay naresolba dito eksakto kung paano ito naresolba sa preview task (kasalukuyang Meshy 7.1), kaya ang isang latest preview at ang latest refine nito ay palaging napupunta sa parehong texture model.

  • Name
    moderation
    Type
    boolean
    default false
    Description

    Kapag itinakda sa true, ang input content ay awtomatikong susuriin para sa potensyal na mapaminsalang content. Kung natukoy ang mapaminsalang content, hindi magpapatuloy ang task sa generation.

    Susuriin ang parehong text mula sa texture_prompt at ang larawan mula sa texture_image_url.

  • Name
    remove_lighting
    Type
    boolean
    default true
    Description

    Nag-aalis ng mga highlight at shadow mula sa base color texture, na nagbubunga ng mas malinis na resulta na mas epektibong gumagana sa ilalim ng custom na lighting setup.

    Nagkakabisa lamang kapag ang ai_model ay meshy-6; hindi ito pinapansin ng ibang mga modelo.

  • Name
    target_formats
    Type
    string[]
    Description

    Tinutukoy kung aling mga 3D file format na isasama sa output. Ang mga hiniling na format lamang ang lilikhain at ibabalik, na maaaring mabawasan ang oras ng pagkumpleto ng task. Kapag hindi isinama, lahat ng suportadong format ay isasama.

    Mga available na value: glb, obj, fbx, stl, usdz, 3mf

    Kapag hindi isinama, lahat ng format maliban sa 3mf ang lilikhain. Ang 3mf ay isasama lamang kapag explicit na tinukoy.

  • Name
    alpha_thumbnail
    Type
    boolean
    default false
    Description

    Kapag itinakda sa true, ang task ay dagdag na naglilikha ng bersyon na may transparent-background (RGBA) ng preview at ibinabalik ito bilang alpha_thumbnail_url sa GET response. Ang umiiral na field na thumbnail_url ay hindi nagbabago.

  • Name
    auto_size
    Type
    boolean
    default false
    Description

    Kapag itinakda sa true, gagamit ang serbisyo ng AI vision para awtomatikong tantiyahin ang real-world na taas ng bagay at ire-resize ang modelo alinsunod dito. Ang origin ay magiging bottom bilang default maliban kung explicit na itinakda ang origin_at.

Naaangkop lamang kapag auto_size = true
  • Name
    origin_at
    Type
    string
    default bottom
    Description

    Posisyon ng origin kapag pinagana ang auto_size.

    Mga available na value: bottom, center.

Mga Ibinabalik

Ang result property ng response ay naglalaman ng task id ng bagong likhang Text to 3D task.

Mga Mode ng Kabiguan

  • Name
    400 - Bad Request
    Description

    Ang request ay hindi katanggap-tanggap. Mga karaniwang dahilan:

    • Invalid task ID: Ang preview_task_id ay invalid o hindi umiiral.
    • Task not ready: Ang preview task ay hindi pa nagtagumpay.
    • Model mismatch: Ang AI model ng preview task ay hindi tugma sa hiniling na refine model.
  • Name
    401 - Unauthorized
    Description

    Nabigo ang authentication. Paki-check ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Hindi sapat na credits para gawin ang task na ito.

  • Name
    404 - Not Found
    Description

    Hindi natagpuan ang preview task na tinukoy ng preview_task_id.

  • Name
    429 - Too Many Requests
    Description

    Nalampasan mo ang iyong rate limit.

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

Kunin ang isang Text to 3D Task

Ang endpoint na ito ay nagbibigay-daan sa iyo upang kunin ang isang Text to 3D task gamit ang isang valid na task id. Sumangguni sa The Text to 3D Task Object upang makita kung aling mga property ang kasama sa Text to 3D task object.

Gumagana ang endpoint na ito para sa parehong preview at refine tasks.

Mga Parameter

  • Name
    id
    Type
    path
    Description

    Natatanging identifier para sa Text to 3D task na kukunin.

Mga Ibinabalik

Ang response ay naglalaman ng Text to 3D task object. Tingnan ang seksyong The Text to 3D Task Object para sa mga detalye.

Mga Halimbawa

ModeSample 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

I-delete ang Text to 3D Task

Permanenteng binubura ng endpoint na ito ang isang Text to 3D task, kabilang ang lahat ng kaugnay na modelo at data. Hindi na maibabalik ang aksyong ito.

Path Parameters

  • Name
    id
    Type
    path
    Description

    Ang ID ng Text to 3D task na ide-delete.

Katayuan ng Task

Ang isang task na PENDING pa ay bubura at ire-refund ang mga credits na nagamit noong panahon ng paggawa nito.

Ang isang task na IN_PROGRESS na ay hindi na maaaring i-delete: tatanggihan ang request na may 409 Conflict at magpapatuloy pa ring tumatakbo ang task. Ang mga credits para sa isang task na naisimulan na ng worker ay hindi na maaaring i-refund, kaya kung ide-delete mo ito habang tumatakbo, mawawala sa iyo kapwa ang credits at ang resulta. Hintayin munang umabot ito sa SUCCEEDED, FAILED, o CANCELED, saka mo ito i-delete.

Ang isang task na nasa terminal state (SUCCEEDED, FAILED, o CANCELED) ay bubura nang walang refund.

Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay, o 409 Conflict kapag ang task ay 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

Ilista ang mga Text to 3D Task

Ang endpoint na ito ay nagbibigay-daan sa iyo na kunin ang isang listahan ng mga Text to 3D task.

Mga Parameter

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Numero ng pahina para sa pagination.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Limitasyon sa laki ng pahina. Ang pinakamataas na pinapayagan ay 100 na item.

  • Name
    sort_by
    Type
    string
    Description

    Field na gagamitin sa pag-sort.

    Mga available na value:

    • +created_at: Pag-sort ayon sa oras ng paglikha nang pataas (ascending).
    • -created_at: Pag-sort ayon sa oras ng paglikha nang pababa (descending).

Mga Ibinabalik na Halaga

Nagbabalik ng isang paginated na listahan ng 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

I-stream ang Text to 3D Task

Ang endpoint na ito ay nag-i-stream ng real-time na mga update para sa isang Text to 3D task gamit ang Server-Sent Events (SSE).

Mga Parameter

  • Name
    id
    Type
    path
    Description

    Natatanging identifier para sa Text to 3D task na i-stream.

Ibinabalik

Nagbabalik ng stream ng The Text to 3D Task Objects bilang Server-Sent Events.

Para sa mga task na PENDING o IN_PROGRESS, ang response stream ay maglalaman lamang ng mga kinakailangang field na progress at status.

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
}

Ang Text to 3D Task Object

Ang Text to 3D Task object ay isang unit of work na ginagamit ng Meshy para bantayan ang paggawa ng 3D model mula sa isang text input. May dalawang stages ang Text to 3D API, preview at refine. Ang preview stage ay para sa paggawa ng mesh-only na 3D model, at ang refine stage ay para sa paggawa ng textured na 3D model base sa resulta ng preview stage.

Ang object ay may mga sumusunod na properties:

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier para sa task. Bagamat gumagamit kami ng k-sortable UUID para sa task ids bilang implementation detail, hindi dapat kang gumawa ng anumang assumption tungkol sa format ng id.

  • Name
    type
    Type
    string
    Description

    Type ng Text to 3D task. Ang posibleng values ay text-to-3d-preview para sa preview stage tasks at text-to-3d-refine para sa refine stage tasks.

  • Name
    model_urls
    Type
    object
    Description

    Downloadable URL sa textured 3D model file na nilikha ng Meshy. Ang property para sa isang format ay hindi isasama kung ang format ay hindi nilikha, sa halip na maglabas ng empty string.

    • Name
      glb
      Type
      string
      Description

      Downloadable URL sa GLB file.

    • Name
      fbx
      Type
      string
      Description

      Downloadable URL sa FBX file.

    • Name
      usdz
      Type
      string
      Description

      Downloadable URL sa USDZ file.

    • Name
      obj
      Type
      string
      Description

      Downloadable URL sa OBJ file.

    • Name
      mtl
      Type
      string
      Description

      Downloadable URL sa MTL file.

    • Name
      stl
      Type
      string
      Description

      Downloadable URL sa STL file.

    • Name
      3mf
      Type
      string
      Description

      Downloadable URL sa 3MF file. Naroroon lang kapag hiningi ang 3mf sa target_formats.

  • Name
    prompt
    Type
    string
    Description

    Ito ang hindi binagong prompt na ginamit upang likhain ang task.

  • Name
    negative_prompt
    Type
    string
    ⚠ lipas na
    Description

    Pinapanatili para sa backward compatibility. Ang field na ito ay walang functional impact sa mga nilikhang model.

  • Name
    art_style
    Type
    string
    ⚠ lipas na
    Description

    Ang hindi binagong art_style na ginamit upang likhain ang preview task. Hindi suportado ng Meshy-6.

  • Name
    texture_richness
    Type
    string
    ⚠ lipas na
    Description

    Pinapanatili para sa backward compatibility. Ang field na ito ay walang functional impact sa mga nilikhang model.

  • Name
    texture_prompt
    Type
    string
    Description

    Karagdagang text prompt na ibinigay upang gabayan ang proseso ng texturing sa panahon ng refine stage.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ lipas na
    Description

    Deprecated; basahin ang geometry_resolution sa halip.

  • Name
    geometry_resolution
    Type
    string
    Description

    Ang Ultra tier na tinakbo ng preview task (2k o 4k); hindi isasama para sa standard.

  • Name
    texture_image_url
    Type
    string
    Description

    Downloadable URL sa texture image na ginamit upang gabayan ang proseso ng texturing.

  • Name
    thumbnail_url
    Type
    string
    Description

    Downloadable URL sa thumbnail image ng model file.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Downloadable URL sa transparent-background (RGBA) na bersyon ng thumbnail_url. Naroroon lang kapag ang task ay nilikha gamit ang alpha_thumbnail: true at matagumpay na na-render ang transparent preview; kung hindi, hindi isasama ang field na ito.

  • Name
    video_url
    Type
    string
    ⚠ lipas na
    Description

    Downloadable URL sa preview video. Aalisin sa susunod na release.

  • Name
    progress
    Type
    integer
    Description

    Progress ng task. Kung hindi pa nasisimulan ang task, ang property na ito ay 0. Kapag nagtagumpay na ang task, ito ay magiging 100.

  • Name
    started_at
    Type
    timestamp
    Description

    Timestamp ng kung kailan sinimulan ang task, sa milliseconds. Kung hindi pa nasisimulan ang task, ang property na ito ay 0.

    Ang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas mula Enero 1, 1970 UTC, ayon sa RFC 3339 standard. Halimbawa, ang Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Ito ay naaangkop sa lahat ng timestamp sa Meshy API.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp ng kung kailan nilikha ang task, sa milliseconds.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp ng kung kailan natapos ang task, sa milliseconds. Kung hindi pa tapos ang task, ang property na ito ay 0.

  • Name
    status
    Type
    string
    Description

    Status ng task. Ang posibleng values ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    texture_urls
    Type
    array
    Description

    Isang array ng texture URL objects na nilikha mula sa task. Karaniwan, isa lang ang nilalaman nito na texture URL object. Ang bawat texture URL ay may mga sumusunod na properties:

    • Name
      base_color
      Type
      string
      Description

      Downloadable URL sa base color map image.

    • Name
      metallic
      Type
      string
      Description

      Downloadable URL sa metallic map image.

      Kung ang task ay nilikha gamit ang enable_pbr: false, hindi isasama ang property na ito.

    • Name
      normal
      Type
      string
      Description

      Downloadable URL sa normal map image.

      Kung ang task ay nilikha gamit ang enable_pbr: false, hindi isasama ang property na ito.

    • Name
      roughness
      Type
      string
      Description

      Downloadable URL sa roughness map image.

      Kung ang task ay nilikha gamit ang enable_pbr: false, hindi isasama ang property na ito.

    • Name
      emission
      Type
      string
      Description

      Downloadable URL sa emission map image.

      Kung ang task ay nilikha gamit ang enable_pbr: false, o ang ai_model ay meshy-6-lite, hindi isasama ang property na ito.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Ang bilang ng mga naunang task.

    Ang value ng field na ito ay may kabuluhan lamang kung ang status ng task ay PENDING.

  • Name
    task_error
    Type
    object
    Description

    Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa kumpletong reference ng task_error object.

  • Name
    consumed_credits
    Type
    integer
    Description

    Ang bilang ng credits na nagamit ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na task (ibinabalik ang credits kapag nabigo).

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
}