Text to 3D API

Ang Text to 3D API ay isang tampok na nagpapahintulot sa iyo na i-integrate ang mga kakayahan ng Text to 3D ng Meshy sa iyong sariling aplikasyon. Dito sa seksyong ito, makakahanap ka ng lahat ng impormasyong kailangan mo upang magsimula sa API na ito.

Gumagamit ang Text to 3D ng dalawang-hakbang na workflow. Una, lumikha ng preview na task (mode: "preview") upang makabuo ng 3D mesh nang walang texture, kaya't maaari mong suriin ang hugis. Pagkatapos, ipasa ang nakumpletong task ID ng preview sa isang refine na task (mode: "refine") upang mag-apply ng texture sa mesh. Parehong hakbang ay ginagamit ang parehong endpoint.

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

Lumikha ng Text to 3D Preview Task

Ang endpoint na ito ay lumilikha ng Text to 3D preview task, na bumubuo ng isang hindi pa texturized na 3D mesh (geometry lamang) mula sa isang text prompt. Ito ang unang hakbang sa dalawang-hakbang na workflow. Kapag nagtagumpay ang preview, gamitin ang ibinalik na task ID upang lumikha ng refine task para sa texturing. Tingnan ang The Text to 3D Task Object para sa buong response schema.

Mga Parameter

  • Name
    mode
    Type
    string
    Kinakailangan
    Description

    Ang field na ito ay dapat itakda sa "preview" kapag lumilikha ng preview task.

  • Name
    prompt
    Type
    string
    Kinakailangan
    Description

    Ilarawan kung anong uri ng bagay ang 3D na modelo. Maximum 600 na karakter.

  • Name
    model_type
    Type
    string
    default standard
    Description

    Tukuyin ang uri ng 3D mesh generation.

    Magagamit na halaga:

    • standard: Regular na mataas na detalye ng 3D mesh generation.
    • smart-topology: Pumili ng Smart Topology model gamit ang ai_model (meshy-t2).
    • lowpoly (deprecated): Lumilikha ng mababang-poly mesh na optimise para sa malinis na polygons. Inirerekumenda naming gamitin ang smart-topology sa halip.

    Kapag pinili ang smart-topology, ang should_remesh at decimation_mode ay walang bisa, at tanging topology: triangle lamang ang tinatanggap.

    Kapag pinili ang lowpoly, ang ai_model, topology, target_polycount, at should_remesh ay walang bisa.

  • Name
    ai_model
    Type
    string
    default latest
    Description

    ID ng modelo na gagamitin. Ang magagamit na halaga ay nakasalalay sa model_type.

    Standard generation (model_type: standard):

    • meshy-5, meshy-6, meshy-7, latest (Meshy 7)

    Smart Topology generation (model_type: smart-topology):

    • meshy-t2 (default): ang Smart Topology model — malinis na topology, mga bahaging nakahiwalay na natively, triangle output, at isang face count na maaari mong itakda sa target_polycount.
  • Name
    ultra_mode
    Type
    boolean
    default false
    Description

    Pinapagana ang Ultra generation para sa mas mataas na katapatan ng geometry na may mas pinong surface na detalye. Ang generation ay tumatagal ng mas matagal at nagdaragdag ng 5 credits.

    Sinusuportahan lamang kapag ang ai_model ay meshy-7 (o latest), at tanging sa preview mode.

  • Name
    should_remesh
    Type
    boolean
    default false (meshy-6, meshy-7), true (others)
    Description

    Kinokontrol kung paganahin ang remesh phase. Para sa pinakamahusay na kalidad ng modelo, inirerekumenda naming iset ang should_remesh sa false.

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

    Tukuyin ang topology ng nabuo na modelo.

    Magagamit na halaga:

    • quad: Lumikha ng isang quad-dominant mesh.
    • triangle: Lumikha ng isang decimated triangle mesh.

    Ang sukat ng Smart Topology ay triangle-only. Ang paghingi sa quad nang sabay sa ai_model: meshy-t2 ay nagreresulta sa error.

  • Name
    decimation_mode
    Type
    integer
    Description

    Paganahin ang adaptive decimation sa pamamagitan ng pagtatakda ng isang polycount level. Kapag naitakda, ang target_polycount ay walang bisa.

    Magagamit na halaga:

    • 1: Adaptive — ultra polycount.
    • 2: Adaptive — high polycount.
    • 3: Adaptive — medium polycount.
    • 4: Adaptive — low polycount.
  • Name
    target_polycount
    Type
    integer
    Description

    Target na bilang ng polygons (faces) sa output. Ang aktwal na bilang ay maaaring lumihis mula sa target depende sa geometry.

    Ang target_polycount ay may bisa sa dalawang independiyenteng kaso:

    • Remesh — gamit ang should_remesh: true sa isang standard na modelo. Ang mesh ay nir-remesh (decimated) sa tinatayang bilang na ito. Saklaw 100 hanggang 300,000, default 30,000. Kung ang decimation_mode ay nakatakda, ito ang may priyoridad at ang target_polycount ay walang bisa.
    • Smart Topology — gamit ang model_type: smart-topology at ang ai_model: meshy-t2. Ang modelo ay ginawa mismo sa bilang ng mukha na ito; walang tumatakbong remesh at ang should_remesh ay hindi kinakailangan. Saklaw 100 hanggang 15,000, default 4,000.
  • Name
    symmetry_mode
    Type
    string
    ⚠ lipas na
    default auto
    Description

    Pinawalang bisa. Ang parameter na ito ay wala nang pagpapakilos sa output.

    Ang field na symmetry_mode ay kumokontrol sa pag-aasal ng simetriya sa proseso ng pagbuo ng modelo.

    Ang mga wastong halaga ay:

    • off: I-off ang simetriya.
    • auto: Awtomatikong nagpapasiya at nagpapataw ng simetriya base sa input geometry.
    • on: Ipinataw ang simetriya habang gumagawa.
  • Name
    pose_mode
    Type
    string
    default ""
    Description

    Tukuyin ang pose mode para sa nabuo na modelo.

    Magagamit na halaga:

    • a-pose: Lumikha ng modelo sa isang A pose.
    • t-pose: Lumikha ng modelo sa isang T pose.
    • "" (walang laman na string): Walang tiyak na pose ang inilapat.
  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ lipas na
    default false
    Description

    Gamitin ang pose_mode sa halip. Kung dapat lumikhang muli ang modelo sa A/T pose.

  • Name
    art_style
    Type
    string
    ⚠ lipas na
    default realistic
    Description

    Hindi sinusuportahan ng Meshy-6. Ang mga kahilingan gamit ang Meshy-6 ay hindi papansin ang art_style, at ilang mga kumbinasyon ay maaaring magdulot ng error. Magagamit na halaga: realistic, sculpture.

    Ang enable_pbr ay dapat na itakda sa false kapag gumagamit ng Sculpture style, habang ang Sculpture style ay gumagawa ng sarili nitong hanay ng PBR maps.

  • Name
    moderation
    Type
    boolean
    default false
    Description

    Kapag nakatakda sa true, ang input na nilalaman ay awtomatikong sisiyasatin sa posibleng mapanganib na nilalaman. Kung nakita ang mapanganib na nilalaman, ang task ay hindi magpapatuloy sa pagbuo.

    Ang teksto mula sa prompt ay sisiyasatin.

  • Name
    target_formats
    Type
    string[]
    Description

    Tinukoy kung aling mga format ng file ng 3D ang isasama sa output. Ang tanging hinihinging mga format ang mabubuo at ibabalik, na maaring magpababa sa oras ng pagtatapos ng task. Kapag hindi isinama, lahat ng suportadong mga format ay isasaalang-alang.

    Magagamit na halaga: glb, obj, fbx, stl, usdz, 3mf

    Kapag hindi isinama, lahat maliban sa 3mf ay nabuo. Ang 3mf ay kasama lamang kapag malinaw na tinukoy.

  • Name
    alpha_thumbnail
    Type
    boolean
    default false
    Description

    Kapag nakatakda sa true, ang task ay karagdagang magre-render ng bersyon ng preview na may transparent na background (RGBA) at ibabalik ito bilang alpha_thumbnail_url sa GET na tugon. Ang umiiral na thumbnail_url field ay hindi nagbabago.

  • Name
    auto_size
    Type
    boolean
    default false
    Description

    Kapag nakatakda sa true, ang serbisyo ay gumagamit ng AI vision upang awtomatikong matantiya ang tunay na taas ng bagay at baguhin ang laki ng modelo ayon doon. Ang pinagmulan ay default sa bottom maliban kung ang origin_at ay malinaw na nakatakda.

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

    Posisyon ng pinagmulan kapag ang auto_size ay pinagana.

    Magagamit na halaga: bottom, center.

Mga Tugon

Ang result na pag-aari ng tugon ay naglalaman ng task id ng bagong nilikha na Text to 3D task.

Mga Mode ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Hindi katanggap-tanggap ang kahilingan. Karaniwang sanhi:

    • Nawawalang parameter: Isang kinakailangang parameter (e.g., prompt, mode) ay nawawala.
    • Hindi wastong parameter: Ang art_style ay hindi isa sa pinapayagang mga halaga.
    • Sobrang haba ng Prompt: Ang prompt ay lumampas sa limitasyon ng karakter.
  • Name
    401 - Unauthorized
    Description

    Nabigo ang authentication. Mangyaring suriin ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Hindi sapat ang credits upang isagawa ang task na ito.

  • Name
    429 - Too Many Requests
    Description

    Naabot mo na 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 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",
  "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

Lumikha ng Text to 3D Refine Task

Ang endpoint na ito ay lumilikha ng Text to 3D refine task, na nag-a-apply ng texture sa isang nakumpletong preview mesh. Dapat 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

    Ang field na ito ay dapat itakda sa "refine" kapag lumilikha 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 na SUCCEEDED.

  • Name
    enable_pbr
    Type
    boolean
    default false
    Description

    Lumikha ng PBR Maps (metallic, roughness, normal) bilang karagdagan sa base color. Isinasama rin ang emission map kapag ang ai_model ay meshy-6, maliban sa texture_resolution: 8k (walang emission map nagawa). Ang meshy-7 (at latest) ay hindi gumagawa ng emission map.

  • Name
    texture_resolution
    Type
    string
    default 2k
    Description

    Base color texture resolution. Isa sa 2k (2048×2048), 4k (4096×4096), o 8k (8192×8192). Mas mataas na resolusyon ay mas maraming detalye ng ibabaw na nahuhuli. Naaangkop lamang sa refine mode.

    Ang 4k at 8k ay nangangailangan ng ai_model meshy-6, meshy-7, o latest. Sa 8k, walang emission map ang nagagawa.

  • Name
    hd_texture
    Type
    boolean
    ⚠ lipas na
    default false
    Description

    Gamitin ang texture_resolution sa halip — katumbas ng texture_resolution: "4k". Kapag pareho itong itinakda, ang texture_resolution ay may pangunguna.

  • Name
    texture_prompt
    Type
    string
    Description

    Magbigay ng karagdagang text prompt upang gabayan ang prosesong texturing. Maximum 600 na karakter.

  • Name
    texture_image_url
    Type
    string
    Description

    Magbigay ng isang 2d imahe upang gabayan ang proseso ng texturing. Kasalukuyan naming sinusuportahan ang mga .jpg, .jpeg, at .png na format.

    May dalawang paraan upang ibigay ang imahe:

    • Publicly accessible URL: Isang URL na naa-access mula sa pampublikong internet
    • Data URI: Isang base64-encoded na data URI ng imahe. Halimbawa ng isang data URI: data:image/jpeg;base64,<your base64-encoded image data>

    Ang pag-texture ng imahe ay maaaring hindi gumana ng maayos kung mayroong malalaking pagkakaiba sa geometry sa pagitan ng orihinal na asset at in-upload na imahe. Tanging isa sa texture_image_url o texture_prompt ang maaaring gamitin upang gabayan ang proseso ng texturing. Kung parehong mga parameter ang ibinigay, pagkatapos ay texture_prompt ang gagamitin upang i-texture ang modelo bilang default.

  • Name
    ai_model
    Type
    string
    default latest
    Description

    ID ng modelo na gagamitin para sa pag-refine. Magagamit na halaga: meshy-5, meshy-6, meshy-7, latest (Meshy 7).

    Ang latest ay lumulutas dito ng eksakto tulad ng sa preview task (kasalukuyang Meshy 7), kaya ang isang latest preview at ang latest na refine ay palaging nasa parehong texture model.

  • Name
    moderation
    Type
    boolean
    default false
    Description

    Kapag nakatakda sa true, ang input na nilalaman ay awtomatikong sisiyasatin sa posibleng mapanganib na nilalaman. Kung nakita ang mapanganib na nilalaman, ang task ay hindi magpapatuloy sa pagbuo.

    Parehong ang teksto mula sa texture_prompt at ang imahe mula sa texture_image_url ay sisiyasatin.

  • Name
    remove_lighting
    Type
    boolean
    default true
    Description

    Tinatanggal ang mga highlight at shadows mula sa base color texture, lumilikha ng mas malinis na resulta na mas maganda sa ilalim ng mga custom na lighting setup.

    Nagtake effect lamang kapag ang ai_model ay meshy-6. Sa meshy-7 (at latest) ang parameter ay tinatanggap ngunit hindi pinapansin.

  • Name
    target_formats
    Type
    string[]
    Description

    Tinukoy kung aling mga format ng file ng 3D ang isasama sa output. Ang tanging hinihinging mga format ay ang mabubuo at ibabalik, na maaring magpababa sa oras ng pagtatapos ng task. Kapag hindi isinama, lahat ng suportadong mga format ay isasaalang-alang.

    Magagamit na halaga: glb, obj, fbx, stl, usdz, 3mf

    Kapag hindi isinama, lahat maliban sa 3mf ay nabuo. Ang 3mf ay kasama lamang kapag malinaw na tinukoy.

  • Name
    alpha_thumbnail
    Type
    boolean
    default false
    Description

    Kapag nakatakda sa true, ang task ay karagdagang magre-render ng bersyon ng preview na may transparent na background (RGBA) at ibabalik ito bilang alpha_thumbnail_url sa GET na tugon. Ang umiiral na thumbnail_url field ay hindi nagbabago.

  • Name
    auto_size
    Type
    boolean
    default false
    Description

    Kapag nakatakda sa true, ang serbisyo ay gumagamit ng AI vision upang awtomatikong matantiya ang tunay na taas ng bagay at baguhin ang laki ng modelo ayon doon. Ang pinagmulan ay default sa bottom maliban kung ang origin_at ay malinaw na nakatakda.

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

    Posisyon ng pinagmulan kapag ang auto_size ay pinagana.

    Magagamit na halaga: bottom, center.

Mga Tugon

Ang result na pag-aari ng tugon ay naglalaman ng task id ng bagong nilikha na Text to 3D task.

Mga Mode ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Hindi katanggap-tanggap ang kahilingan. Karaniwang sanhi:

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

    Nabigo ang authentication. Mangyaring suriin ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Hindi sapat ang credits upang isagawa ang task na ito.

  • Name
    404 - Not Found
    Description

    Ang preview task na tinukoy ng preview_task_id ay hindi natagpuan.

  • Name
    429 - Too Many Requests
    Description

    Naabot mo na 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 Text to 3D Task

Ang endpoint na ito ay nagpapahintulot sa iyo na makuha ang Text to 3D task gamit ang isang wasto na task id. Suriin ang The Text to 3D Task Object upang makita kung aling mga katangian ang kasama sa Text to 3D task object.

Ang endpoint na ito ay gumagana 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 Tugon

Ang tugon ay naglalaman ng Text to 3D task object. Tingnan ang The Text to 3D Task Object na seksyon 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

Tanggalin ang Text to 3D Task

Ang endpoint na ito ay permanenteng nagtatanggal ng Text to 3D task, kasama ang lahat ng kaugnay na modelo at data. Ang pagkilos na ito ay hindi na mababawi.

Mga Path Parameters

  • Name
    id
    Type
    path
    Description

    Ang ID ng Text to 3D task na dapat tanggalin.

Mga Tugon

Nagbabalik ng 200 OK sa tagumpay.

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

// Nagbabalik ng 200 Ok sa tagumpay.
GET/openapi/v2/text-to-3d

Listahan ng Mga Text to 3D Tasks

Ang endpoint na ito ay nagbibigay-daan sa iyo na makuha ang listahan ng Text to 3D tasks.

Mga Parameter

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Numero ng pahina para sa pagination.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Pagination limit. Maximum na pinapayagan ay 50 na item.

  • Name
    sort_by
    Type
    string
    Description

    Field na pagbabatayan ng pagkakasunod-sunod.

    Magagamit na halaga:

    • +created_at: Ayusin ayon sa oras ng paglikha sa angat ascendasyon.
    • -created_at: Ayusin ayon sa oras ng paglikha sa pababang descendasyon.

Mga Tugon

Nagbabalik ng listahang may pagination 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

Stream ng Text to 3D Task

Ang endpoint na ito ay nag-stream ng real-time na updates 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.

Mga Tugon

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

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

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.
// Para sa mga PENDING o IN_PROGRESS na task, ang response stream ay hindi magsasama ng lahat ng mga field.
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 yunit ng trabaho na sinusubaybayan ng Meshy upang makabuo ng 3D na modelo mula sa isang text input. May dalawang yugto ng Text to 3D API, preview at refine. Ang yugto ng preview ay para sa pagbuo ng mesh-only 3D na modelo, at ang yugto ng refine ay para sa pagbuo ng texturized 3D na modelo base sa resulta ng yugto ng preview.

Ang object ay may mga sumusunod na katangian:

Mga Katangian

  • Name
    id
    Type
    string
    Description

    Natatanging identifier para sa task. Bagaman gumagamit kami ng isang k-sortable na UUID para sa mga id ng task bilang detalye ng pagpapatupad, hindi ka dapat gumawa ng anumang mga palagay tungkol sa format ng id.

  • Name
    type
    Type
    string
    Description

    Type ng Text to 3D task. Posibleng halaga ay text-to-3d-preview para sa mga preview stage na tasks at text-to-3d-refine para sa mga refine stage na tasks.

  • Name
    model_urls
    Type
    object
    Description

    Downloadable na URL sa texturized na 3D na model file na binuo ng Meshy. Ang property para sa isang format ay dapat alisin kung ang format ay hindi nabuo sa halip ng pagbabalik ng walang laman na string.

    • Name
      glb
      Type
      string
      Description

      Downloadable na URL sa GLB file.

    • Name
      fbx
      Type
      string
      Description

      Downloadable na URL sa FBX file.

    • Name
      usdz
      Type
      string
      Description

      Downloadable na URL sa USDZ file.

    • Name
      obj
      Type
      string
      Description

      Downloadable na URL sa OBJ file.

    • Name
      mtl
      Type
      string
      Description

      Downloadable na URL sa MTL file.

    • Name
      stl
      Type
      string
      Description

      Downloadable na URL sa STL file.

    • Name
      3mf
      Type
      string
      Description

      Downloadable na URL sa 3MF file. Presente lamang kapag ang 3mf ay hiniling sa target_formats.

  • Name
    prompt
    Type
    string
    Description

    Ito ay hindi binagong prompt na ginamit upang lumikha ng task.

  • Name
    negative_prompt
    Type
    string
    ⚠ lipas na
    Description

    Pinapanatili para sa likod pagkakatugma. Ang field na ito ay walang function na epekto sa mga binuong modelo.

  • Name
    art_style
    Type
    string
    ⚠ lipas na
    Description

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

  • Name
    texture_richness
    Type
    string
    ⚠ lipas na
    Description

    Pinapanatili para sa likod pagkakatugma. Ang field na ito ay walang function na epekto sa mga binuong modelo.

  • 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
    Description

    Ipinapakita ang halaga ng ultra_mode kung saan nilikha ang preview task. Presente lamang para sa meshy-7 (o latest) na mga preview task na hayagang nagtakda ng ultra_mode; kung hindi ay hindi isama.

  • Name
    texture_image_url
    Type
    string
    Description

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

  • Name
    thumbnail_url
    Type
    string
    Description

    Downloadable na URL sa thumbnail image ng model file.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Downloadable na URL sa isang transparent-background (RGBA) na bersyon ng thumbnail_url. Presente lamang kapag ang task ay nilikha gamit ang alpha_thumbnail: true at ang transparent na preview ay matagumpay na nai-render; kung hindi ang field na ito ay hindi kasama.

  • Name
    video_url
    Type
    string
    ⚠ lipas na
    Description

    Downloadable na URL sa preview video. Alisin sa mga susunod na release.

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

    Ang timestamp ay kumakatawan sa bilang ng mga milliseconds na lumipas simula Enero 1, 1970 UTC, sumusunod sa ang RFC 3339 pamantayan. Halimbawa, Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Ito ay nag-aapply sa lahat ng mga timestamps sa Meshy API.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp kung kailan nilikha ang task, sa milliseconds.

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    texture_urls
    Type
    array
    Description

    Isang array ng mga texture URL objects na binuo mula sa task. Karaniwan itong naglalaman ng isa na texture URL object lamang. Ang bawat texture URL ay may sumusunod na mga property:

    • Name
      base_color
      Type
      string
      Description

      Downloadable na URL sa base color map image.

    • Name
      metallic
      Type
      string
      Description

      Downloadable na URL sa metallic map image.

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

    • Name
      normal
      Type
      string
      Description

      Downloadable na URL sa normal map image.

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

    • Name
      roughness
      Type
      string
      Description

      Downloadable na URL sa roughness map image.

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

    • Name
      emission
      Type
      string
      Description

      Downloadable na URL sa emission map image.

      Kung ang task ay nilikha gamit ang enable_pbr: false, o ai_model ay meshy-5, ang property na ito ay mamemete.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Ang bilang ng mga naunang tasks.

    Ang halaga ng field na ito ay makabuluhan 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 buong reference ng task_error object.

  • Name
    consumed_credits
    Type
    integer
    Description

    Ang bilang ng credits na kinonsumo ng task na ito. Presente kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na task (ang credits ay na-refund sa pagkabigo).

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
}