Text to 3D API

Gumawa ng mga 3D model mula sa text prompts sa sarili mong aplikasyon.

Gumagana ang Text to 3D sa dalawang hakbang. Una, gumawa ng preview task (mode: "preview") para gumawa ng 3D mesh na walang texture, para matingnan mo ang hugis. Pagkatapos, ipadala ang task ID ng matagumpay na preview sa isang refine task (mode: "refine") para i-texture ang mesh. Parehong hakbang ay gumagamit ng parehong endpoint.

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

Create a Text to 3D preview task

Gumagawa ng Text to 3D preview task, na bumubuo ng hindi pa na-texture na 3D mesh (heometriya lang) mula sa isang text prompt. Ito ang unang hakbang ng dalawang-hakbang na workflow. Matapos magtagumpay ang preview, ipadala ang task ID nito sa isang refine task para i-texture ang mesh. Tingnan ang Create a Text to 3D refine task. Para sa buong response schema, tingnan ang The Text to 3D task object.

Tumatakbo ang task sa background. Para malaman kung gaano karaming oras karaniwang tatagal ang isang task, tingnan ang Processing times.

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

Mga Parameter

Name
mode
Type
string
Kinakailangan
Description
Ang hakbang ng dalawang-hakbang na workflow. Ipadala ang preview para gumawa ng preview task.
Name
prompt
Type
string
Kinakailangan
Description
Tekstong naglalarawan sa bagay na gagawin, hanggang 800 character. Ang mas mahabang teksto ay magbabalik ng 400.
Name
model_type
Type
string
default standard
Description
Ang uri ng 3D mesh na gagawin.
Mga magagamit na value:
- standard: isang 3D mesh na may mataas na detalye
- smart-topology: isang Smart Topology mesh. Piliin ang modelo gamit ang ai_model (meshy-t2 o meshy-t2.5).
Kapag smart-topology, hindi pinapansin ng Meshy ang should_remesh at decimation_mode, at tanging topology: triangle lang ang tinatanggap.
Name
ai_model
Type
string
default latest
Description
Ang AI model na bumubuo ng 3D model. Depende ang mga magagamit na value sa model_type.
Standard models (model_type: standard):
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (deprecated): ipadala na lamang ang meshy-7.1
Smart Topology models (model_type: smart-topology):
- meshy-t2: mas malinis na topology, likas na hiwalay na mga bahagi, triangle output, at bilang ng mukha na itinatakda mo gamit ang target_polycount
- meshy-t2.5 (default): mas matalas na detalye para sa mga asset ng laro, triangle output, at bilang ng mukha na itinatakda mo gamit ang target_polycount
Name
geometry_resolution
Type
string
default standard
Description
Ang geometry generation pass. Nalalapat lang ito sa mga preview task. Ang refine na may parameter na ito ay magbabalik ng 400.
Mga magagamit na value:
- standard
- 2k: nagpapatakbo ng Ultra pass sa 2048³
- 4k: nagpapatakbo ng Ultra pass sa 4096³, para sa mas pinong detalye ng ibabaw
Kailangan ng 2k ang meshy-7.1, latest, o ang deprecated na meshy-7. Kailangan ng 4k ang meshy-7.1 o latest. Ang ibang modelo ay magbabalik ng 400.
Name
ultra_mode
Type
boolean
⚠ lipas na
default false
Description
Ipadala na lamang ang geometry_resolution. Ang ultra_mode: true ay katumbas ng geometry_resolution: "2k".
Name
should_remesh
Type
boolean
default true (meshy-6-lite), false (other models)
Description
Kung i-remesh ba ang modelo matapos itong buuin. Para sa pinakamataas na kalidad ng 3D model, ipadala ang false.

Naaangkop lamang kapag should_remesh = true

Name
topology
Type
string
default triangle
Description
Ang uri ng mukha ng na-remesh na modelo.
Mga magagamit na value:
- quad: isang mesh na mas maraming quad
- triangle: isang na-decimate na triangle mesh
Ang output ng Smart Topology ay triangle lamang. Ang pagpapadala ng quad kasama ang ai_model na meshy-t2 o meshy-t2.5 ay magbabalik ng 400.
Name
decimation_mode
Type
integer
Description
Adaptive na bilang ng mukha, ayon sa antas. Kapag itinakda mo ito, hindi pinapansin ng Meshy ang target_polycount.
Mga magagamit na value:
- 1: ultra
- 2: mataas
- 3: katamtaman
- 4: mababa

Name
target_polycount
Type
integer
Description
Ang target na bilang ng mukha. Maaaring magkaiba ang resulta sa target, depende sa heometriya. Nalalapat ito sa dalawang magkahiwalay na kaso:
- Remesh: sa should_remesh: true sa isang standard na modelo. Nire-remesh (dine-decimate) ng Meshy ang mesh sa humigit-kumulang sa bilang na ito. Kung itinakda mo ang decimation_mode, ginagamit ito ng Meshy at hindi pinapansin ang target_polycount.
- Smart Topology: sa model_type: smart-topology at ai_model na meshy-t2 o meshy-t2.5. Direktang bumubuo ang Meshy ng modelo sa bilang ng mukhang ito. Walang remesh na tatakbo, at hindi mo kailangan ang should_remesh.
Ipinapakita ng sumusunod na talahanayan ang saklaw at default para sa bawat kaso:
Kaso Saklaw Default
Remesh 100 hanggang 300000 30000
meshy-t2 100 hanggang 15000 4000
meshy-t2.5 100 hanggang 30000 15000
Ang value na labas sa saklaw ay magbabalik ng 400.

Kaso	Saklaw	Default
Remesh	`100` hanggang `300000`	`30000`
`meshy-t2`	`100` hanggang `15000`	`4000`
`meshy-t2.5`	`100` hanggang `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ lipas na
default auto
Description
Huwag isama. Hindi nakakaapekto ang parameter na ito sa output.
Mga magagamit na value:
- off: nagdi-disable ng simetriya
- auto: naglalapat ng simetriya batay sa input na heometriya
- on: nagpapatupad ng simetriya habang bumubuo
Name
pose_mode
Type
string
default ""
Description
Ang pose ng binuong modelo.
Mga magagamit na value:
- a-pose: isang A pose
- t-pose: isang T pose
- "" (walang laman na string): walang tiyak na pose
Name
is_a_t_pose
Type
boolean
⚠ lipas na
default false
Description
Ipadala na lamang ang pose_mode. Kung bubuuin ba ang modelo sa A pose o T pose.
Name
art_style
Type
string
⚠ lipas na
default realistic
Description
Huwag isama. Hindi ito pinapansin ng Meshy.
Name
moderation
Type
boolean
default false
Description
Kung susuriin ba ang prompt para sa nakakapinsalang content bago bumuo. Kung makakita ang Meshy ng nakakapinsalang content, magbabalik ang kahilingan ng 400 at hindi gagawa ng task ang Meshy.
Name
target_formats
Type
string[]
Description
Ang mga file format na gagawin. Bubuo at ibabalik lang ng Meshy ang mga format na ito, na maaaring magpaikli sa task. Kung hindi mo isasama ito, bubuo ang Meshy ng bawat format maliban sa 3mf, na bubuuin lang nito kapag hiniling mo.
Mga magagamit na value:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
default false
Description
Kung magre-render din ba ng preview na may transparent na background (RGBA), na ibabalik sa alpha_thumbnail_url kapag kinuha mo ang task. Hindi nagbabago ang thumbnail_url.
Name
auto_size
Type
boolean
default false
Description
Kung tatantyahin ba ang tunay na taas ng bagay gamit ang AI vision at i-resize ang modelo sa taas na iyon. Inilalagay ng Meshy ang origin sa ilalim maliban kung itinakda mo ang origin_at.

Naaangkop lamang kapag auto_size = true

Name
origin_at
Type
string
default bottom
Description
Kung saan ilalagay ang origin ng modelo, bottom o center.

Ibinabalik

Ang result field ng response ay naglalaman ng ID ng bagong Text to 3D task.

Mga Mode ng Pagkabigo

Name
400 - Bad Request
Description
Hindi matatakbo ang kahilingan. Sinasabi ng error message kung anong problema ang nakita nito. Halimbawa:
- Missing parameter: Nawawala ang isang kinakailangang parameter, tulad ng prompt o mode.
- Prompt too long: Lampas na sa character limit ang prompt.
- Unsupported model for Ultra: 2k o 4k ang geometry_resolution, gamit ang ai_model na hindi ito kayang patakbuhin.
Ayusin ang kahilingan, pagkatapos ay ipadala ito ulit. Tingnan ang Errors.
Name
401 - Unauthorized
Description
Nawawala o hindi wasto ang API key. Suriin ang Authorization header.
Name
402 - Payment Required
Description
Halimbawa:
- Insufficient credits: Walang sapat na credits ang account para sa task na ito, o naabot na ng account ang limitasyon sa credit. Suriin ang iyong credit balance, pagkatapos ay subukan ulit.
- Free plan: Kailangan ng bayad na plano para makagawa ng task. I-upgrade ang iyong plano sa iyong subscription settings, pagkatapos ay subukan ulit.
Name
403 - Forbidden
Description
Hinarang ng content moderation ang prompt o isang input na larawan. Baguhin ang input, pagkatapos ay subukan ulit.
Name
429 - Too Many Requests
Description
Nalagpasan mo ang iyong rate limit. Maghintay, pagkatapos ay subukan ulit. Tingnan ang Rate limits.

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

Create a Text to 3D refine task

Gumagawa ng Text to 3D refine task, na nagta-texture sa mesh ng isang nakumpletong preview task. Ipadala ang ID ng isang matagumpay na preview task bilang preview_task_id. Tingnan ang Create a Text to 3D preview task. Ito ang ikalawang hakbang sa two-step workflow.

Tumatakbo ang task sa background. Para sa karaniwang tagal ng isang task, tingnan ang Processing times.

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

Mga Parameter

Name
mode
Type
string
Kinakailangan
Description
Ang hakbang sa two-step workflow. Ipadala ang refine para gumawa ng refine task.
Name
preview_task_id
Type
string
Kinakailangan
Description
Ang ID ng preview task na ite-texture. Dapat ang status ng preview task ay SUCCEEDED.
Name
enable_pbr
Type
boolean
default false
Description
Kung gagawa rin ng PBR maps (metallic, roughness, at normal) kasama ang base color.
Sa ai_model na meshy-6, gumagawa rin si Meshy ng emission map, maliban sa texture_resolution: 8k. Ang meshy-6-lite, meshy-7, meshy-7.1, at latest ay hindi gumagawa ng emission map. Ganoon din ang refine ng meshy-t2 o meshy-t2.5 preview na hindi nagtakda ng ai_model. Sa ai_model: meshy-n1, ang true ay magbabalik ng 400.
Name
texture_resolution
Type
string
default 2k
Description
Ang resolution ng base color texture. Para lamang ito sa refine tasks. Ang preview na may ganitong parameter ay magbabalik ng 400.
Mga magagamit na value:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Mas maraming detalye ng ibabaw ang nakukuha sa mas mataas na resolution. Kailangan ng 4k at 8k ang ai_model na meshy-6, meshy-7.1, o latest. Sa meshy-n1, magbabalik ito ng 400. Sa 8k, hindi gumagawa si Meshy ng emission map.
Name
hd_texture
Type
boolean
⚠ lipas na
default false
Description
Ipadala na lang ang texture_resolution. Ang hd_texture: true ay pareho sa texture_resolution: "4k". Kung ipapadala mo pareho, gagamitin ni Meshy ang texture_resolution.
Name
texture_prompt
Type
string
Description
Teksto na gagabay sa pag-texture, hanggang 800 character. Ang mas mahabang teksto ay magbabalik ng 400. Ipadala ang texture_prompt o texture_image_url, hindi pareho. Kung ipapadala mo pareho, gagamitin ni Meshy ang texture_prompt. Sa ai_model: meshy-n1, ang pagpapadala nito ay magbabalik ng 400.
Name
texture_image_url
Type
string
Description
Isang 2D na larawan na gagabay sa pag-texture, bilang isang pampublikong URL o base64-encoded na data URI, tulad ng data:image/jpeg;base64,<your base64-encoded image data>.
Dapat ang larawan ay isang .jpg, .jpeg, .png, o .webp na file na hindi hihigit sa 20 MB, hindi bababa sa 32 pixels sa bawat gilid, at hindi hihigit sa 178,956,970 pixels (lapad × taas).
Sa ai_model: meshy-n1, nagte-texture si Meshy mula sa larawang ito bilang front view.
Maaaring hindi gumana nang maayos ang pag-texture mula sa isang larawan kapag malaki ang pagkakaiba ng hugis sa larawan kumpara sa modelo.
Name
ai_model
Type
string
default inherited from the preview task
Description
Ang AI model na nagte-texture sa mesh.
Mga magagamit na value:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-n1: 2K base color texture mula lamang sa reference image. Walang text prompt, walang PBR maps, walang 4K o 8K.
- meshy-7 (deprecated): ipadala na lang ang meshy-7.1
Huwag isama para gamitin ang model ng preview task, para patakbuhin ang preview at ang refine nito sa parehong model mula simula hanggang katapusan. Magpadala ng value para i-override ito. Ang tahasang latest ay nalulutas sa parehong paraan tulad ng sa preview task, kaya ang latest na preview at ang latest na refine nito ay palaging gumagamit ng parehong texture model.
Sa meshy-n1, nagte-texture si Meshy mula sa texture_image_url. Kung wala ito, ginagamit ni Meshy ang reference image na iniimbak ng meshy-7.1 o latest na preview. Ang alinmang ibang preview ay magbabalik ng 400 maliban kung magpadala ka ng texture_image_url. Ang preview ay maaaring magkaroon ng hanggang 7,999,999 na triangles. Ang preview na na-remesh sa quads ay magbabalik ng 400.
Name
moderation
Type
boolean
default false
Description
Kung susuriin ang texture_prompt at texture_image_url para sa mapanganib na content bago mag-generate. Kung makakita si Meshy ng mapanganib na content, magbabalik ng 400 ang request at hindi gagawa ng task si Meshy.
Name
remove_lighting
Type
boolean
default true
Description
Kung aalisin ang mga highlight at shadow mula sa base color texture. Mas gumagana nang maayos ang mas malinis na resulta sa ilalim ng custom na ilaw.
Nagiging epektibo lamang kapag ang ai_model ay meshy-6. Tinatanggap ito ng meshy-7.1 at latest ngunit hindi ito pinapansin, at gayon din ang refine ng meshy-t2 o meshy-t2.5 preview na hindi nagtakda ng ai_model. Ang pagpapadala nito kasama ang meshy-6-lite ay magbabalik ng 400. Sa meshy-n1, ang true ay magbabalik ng 400.
Name
target_formats
Type
string[]
Description
Ang mga file format na gagawin. Gagawa at ibabalik lamang ni Meshy ang mga format na ito, na maaaring magpaikli sa task. Kung hindi mo isasama ito, gagawa si Meshy ng bawat format maliban sa 3mf, na gagawin lamang nito kapag hiniling mo ito.
Mga magagamit na value:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
default false
Description
Kung gagawa rin ng preview na may transparent na background (RGBA), na ibabalik sa alpha_thumbnail_url kapag kinuha mo ang task. Hindi nagbabago ang thumbnail_url.
Name
auto_size
Type
boolean
default false
Description
Kung tatantiyahin ang tunay na taas ng bagay gamit ang AI vision at ire-resize ang modelo dito. Inilalagay ni Meshy ang origin sa ibaba maliban kung itatakda mo ang origin_at.

Naaangkop lamang kapag auto_size = true

Name
origin_at
Type
string
default bottom
Description
Kung saan ilalagay ang origin ng modelo, bottom o center.

Mga Ibabalik

Ang result field ng response ay naglalaman ng ID ng bagong Text to 3D task.

Mga mode ng kabiguan

Name
400 - Bad Request
Description
Hindi matatakbo ang request. Sinasabi ng error message kung anong problema ang natagpuan nito. Halimbawa:
- Invalid task ID: Hindi valid ang preview_task_id, o hindi ito tumutugma sa alinman sa iyong mga preview task.
- Task not ready: Hindi pa matagumpay ang preview task.
- Model mismatch: Hindi gumagana ang AI model ng preview task kasama ang hiniling na refine model.
- Unsupported model for remove_lighting: Ipinadala ang remove_lighting kasama ang ai_model: "meshy-6-lite".
- No reference image for Meshy N1: Ipinadala ang ai_model: meshy-n1 nang walang texture_image_url, at walang reference image ang preview na magagamit ng Meshy N1. Ipadala ang texture_image_url.
- Quad preview for Meshy N1: Ipinadala ang ai_model: meshy-n1 para sa isang preview na na-remesh sa quads. I-refine ito gamit ang ibang ai_model.
- Too many triangles for Meshy N1: Sa ai_model: meshy-n1, ang preview ay may higit sa 7,999,999 triangles. I-refine ito gamit ang ibang ai_model.
- Unsupported option for Meshy N1: Ipinadala ang ai_model: meshy-n1 kasama ang isa sa mga opsyong ito:
  - texture_prompt
  - enable_pbr: true
  - texture_resolution na 4k o 8k
  - hd_texture: true nang walang texture_resolution
  - remove_lighting: true
Ayusin ang request, pagkatapos ay ipadala muli ito. Tingnan ang Errors.
Name
401 - Unauthorized
Description
Nawawala o hindi valid ang API key. Suriin ang Authorization header.
Name
402 - Payment Required
Description
Halimbawa:
- Insufficient credits: Walang sapat na credits ang account para sa task na ito, o naabot na ng account ang credit limit nito. Suriin ang iyong credit balanse, pagkatapos ay subukan muli.
- Free plan: Nangangailangan ng bayad na plan ang paggawa ng task. I-upgrade ang iyong plan sa iyong subscription settings, pagkatapos ay subukan muli.
Name
403 - Forbidden
Description
Hinarang ng content moderation ang prompt o isang input na larawan. Baguhin ang input, pagkatapos ay subukan muli.
Name
429 - Too Many Requests
Description
Lumampas ka sa iyong rate limit. Maghintay, pagkatapos ay subukan muli. Tingnan ang Rate limits.

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

Kumuha ng Text to 3D task

Ibinabalik ang isang Text to 3D task batay sa ID nito. Gumagana ito para sa parehong preview at refine tasks.

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
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa create response.

Ibinabalik

Ang Text to 3D task object.

Mga Halimbawa

Ipinapakita ng sumusunod na talahanayan ang isang sample na modelo para sa bawat mode.

Mode	Sample na modelo
Preview
Refine

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

Delete a Text to 3D task

Permanenteng binubura nito ang isang Text to 3D task, kabilang ang mga model at data nito. Hindi mo na maaaring bawiin ang isang pagbura.

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

Path parameters

Name
id
Type
path
Description
Ang ID ng task na buburahin.

Status ng task

Ang pagbura sa isang PENDING na task ay nagre-refund ng mga credits na ginamit nito noong ginawa mo ito.

Hindi maaaring burahin ang isang IN_PROGRESS na task. Ibabalik ng request ang 409 Conflict, at magpapatuloy ang pagtakbo ng task. Hindi nire-refund ng Meshy ang isang task na nagsimula na, kaya ang pagbura nito ay magkakahalaga sa iyo ng mga credits at ng resulta. Hintayin itong umabot sa SUCCEEDED, FAILED, o CANCELED, pagkatapos ay burahin ito.

Ang pagbura sa isang task na nasa final status (SUCCEEDED, FAILED, o CANCELED) ay hindi nagre-refund ng mga credits nito.

Mga ibinabalik na halaga

200 OK kapag nabura na ang task, o 409 Conflict kapag ang task ay IN_PROGRESS.

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

I-list ang mga Text to 3D na gawain

Nagbabalik ng listahan ng iyong mga Text to 3D na gawain.

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

Mga Parameter

Name
page_num
Type
integer
default 1
Description
Ang numero ng pahinang ibabalik, hanggang 255. Ang mas malaking halaga ay nagbabalik ng 400.
Name
page_size
Type
integer
default 10
Description
Ang bilang ng mga gawain bawat pahina, hanggang 100.
Name
sort_by
Type
string
Description
Ang pagkakasunod-sunod ng pag-uuri.
Mga magagamit na halaga:
- +created_at: pinakaluma muna
- -created_at: pinakabago muna

Mga Ibinabalik

Isang paginated na listahan ng Text to 3D task objects.

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

Mag-stream ng Text to 3D task

Nagsa-stream ng mga update ng Text to 3D task bilang 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
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa create response.

Ibinabalik

Isang stream ng Text to 3D task objects bilang Server-Sent Events.

Bawat event ay may hawak na buong task object, sa parehong anyo na ibinabalik ng Get endpoint. Habang ang task ay PENDING o IN_PROGRESS, wala pang mga value ang mga result field nito.

The Text to 3D task object

Ang Text to 3D task object ay naglalarawan ng isang task na bumubuo ng 3D model mula sa isang text prompt. Hawak nito ang status, ang progress, at ang mga model file kapag matagumpay ang task. May dalawang stage ang Text to 3D, ang preview at refine. Ang isang preview task ay bumubuo ng mesh-only na 3D model, at ang isang refine task ay bumubuo ng textured na 3D model mula sa resulta ng preview.

Mga 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
Ang task ID. Ituring itong isang opaque string, at huwag umasa sa format nito.
Name
type
Type
string
Description
Ang task type, text-to-3d-preview para sa isang preview task o text-to-3d-refine para sa isang refine task.
Name
model_urls
Type
object
Description
Mga download URL para sa binuong 3D model, isa para sa bawat file format. Ang format na hindi binuo ng task ay walang key, sa halip na isang blangkong string.
- Name
  glb
  Type
  string
  Description
  Ang GLB file.
- Name
  fbx
  Type
  string
  Description
  Ang FBX file.
- Name
  usdz
  Type
  string
  Description
  Ang USDZ file.
- Name
  obj
  Type
  string
  Description
  Ang OBJ file.
- Name
  mtl
  Type
  string
  Description
  Ang MTL file.
- Name
  stl
  Type
  string
  Description
  Ang STL file.
- Name
  3mf
  Type
  string
  Description
  Ang 3MF file. Naroroon lamang kapag kasama ang 3mf sa target_formats.
Name
prompt
Type
string
Description
Ang prompt na ipinadala mo para gawin ang task, hindi binago.
Name
texture_prompt
Type
string
Description
Ang text prompt na ipinadala mo para gabayan ang texturing sa refine stage.
Name
ultra_mode
Type
boolean
⚠ lipas na
Description
Basahin na lamang ang geometry_resolution.
Name
geometry_resolution
Type
string
Description
Ang Ultra tier na pinatakbo ng preview task, 2k o 4k. Wala ang field na ito para sa standard.
Name
texture_image_url
Type
string
Description
Download URL para sa larawang ipinadala mo para gabayan ang texturing.
Name
thumbnail_url
Type
string
Description
Download URL para sa isang thumbnail image ng 3D model.
Name
alpha_thumbnail_url
Type
string
Description
Download URL para sa isang bersyon ng thumbnail_url na may transparent na background (RGBA). Naroroon lamang kapag ginawa mo ang task gamit ang alpha_thumbnail: true at na-render ni Meshy ang transparent na preview.
Name
progress
Type
integer
Description
Kung gaano karami ang natapos sa task, bilang isang porsyento. Ito ay 0 hanggang magsimula ang task at 100 kapag ito ay nagtagumpay.
Name
started_at
Type
timestamp
Description
Oras na nagsimula ang task, sa Unix milliseconds. Ito ay 0 hanggang magsimula ang task.
Name
created_at
Type
timestamp
Description
Oras na ginawa ang task, sa Unix milliseconds.
Name
finished_at
Type
timestamp
Description
Oras na natapos ang task, sa Unix milliseconds. Ito ay 0 hanggang matapos ang task.
Name
status
Type
string
Description
Ang status ng task, isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, o CANCELED.
Name
texture_urls
Type
array
Description
Mga download URL para sa mga binuong texture map, bilang isang array ng mga object. Karaniwan itong may hawak na isang object. Ang bawat object ay may mga sumusunod na field:
- Name
  base_color
  Type
  string
  Description
  Ang base color map.
- Name
  metallic
  Type
  string
  Description
  Ang metallic map. Wala kapag ginawa mo ang task gamit ang enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Ang normal map. Wala kapag ginawa mo ang task gamit ang enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Ang roughness map. Wala kapag ginawa mo ang task gamit ang enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Ang emission map. Wala sa alinman sa mga sumusunod na kaso:
  
  Ginawa mo ang task gamit ang enable_pbr: false.
  
  Ang ai_model ay meshy-6-lite, meshy-7, meshy-7.1, o latest.
  
  Ang texture_resolution ay 8k.
  
  Ni-refine ng task ang isang meshy-t2 o meshy-t2.5 preview nang hindi itinatakda ang ai_model.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga task na nauuna sa task na ito sa queue. Makabuluhan lamang ang value habang PENDING ang task.
Name
task_error
Type
object
Description
Ang mga detalye ng error kapag nabigo ang task. Ito ay null maliban kung ang status ay FAILED. Tingnan ang Errors.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na ginamit ng task. Naroroon kapag ang status ay PENDING, IN_PROGRESS, o SUCCEEDED. Ito ay 0 para sa isang FAILED na task, dahil ibinabalik ni Meshy ang credits kapag nabigo ang isang task.