Image to 3D API

Ang Image to 3D API ay isang feature na nagbibigay-daan sa iyong i-integrate ang mga kakayahan ng Image to 3D ng Meshy sa sarili mong application. Sa seksyong ito, makikita mo ang lahat ng impormasyong kailangan mo para makapagsimula sa API na ito.

POST/openapi/v1/image-to-3d

Gumawa ng Image to 3D Task

Ang endpoint na ito ay nagbibigay-daan sa iyo upang gumawa ng bagong Image to 3D task. Sumangguni sa The Image to 3D Task Object upang makita kung aling mga properties ang kasama sa Image to 3D task object.

Tumatakbo ang task sa background. Para sa karaniwang tagal, tingnan ang Processing Times.

Mga Parameter

Isa lamang sa input_task_id o image_url ang kinakailangan. Kung parehong ibinigay, ang input_task_id ang mananaig.

Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng isang nakumpletong image-generation task na ang output ay dapat gamitin bilang input image. Ang task na ito ay dapat isa sa mga sumusunod na task: Text to Image o Image to Image. Bukod dito, dapat itong patakbuhin sa pamamagitan ng API, may status na SUCCEEDED, at makagawa ng eksaktong isang imahe.

Name
image_url
Type
string
Kinakailangan
Description
Magbigay ng imahe para gamitin ni Meshy sa paggawa ng model. Kasalukuyan naming sinusuportahan ang mga format na .jpg, .jpeg, .png, at .webp.
Pinakamataas na laki ng file: 20 MB.
May dalawang paraan upang magbigay ng imahe:
- Publicly accessible URL: Isang URL na naa-access mula sa pampublikong internet.
- Data URI: Isang base64-encoded data URI ng imahe. Halimbawa ng data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
model_type
Type
string
default standard
Description
Tukuyin ang uri ng 3D mesh generation.
Mga available na value:
- standard: Karaniwang high-detail na 3D mesh generation.
- smart-topology: Pumili ng Smart Topology model gamit ang ai_model (meshy-t2 o meshy-t2.5).
- lowpoly (deprecated, iretiro sa Oktubre 30, 2026): Gumagawa ng low-poly mesh na in-optimize para sa mas malinis na mga polygon. Inirerekomenda namin ang Meshy T2.5 sa halip: smart-topology gamit ang meshy-t2.5.
Kapag pinili ang smart-topology, hindi papansinin ang should_remesh, save_pre_remeshed_model, at decimation_mode, at topology: triangle lamang ang tatanggapin.
Ire-retire ang lowpoly sa Oktubre 30, 2026. Pagkalipas ng petsang iyon, ang mga request na may model_type: "lowpoly" ay magbabalik ng error. Inirerekomenda naming lumipat sa Meshy T2.5 (model_type: "smart-topology" gamit ang ai_model: "meshy-t2.5"). Kapag pinili ang lowpoly, hindi papansinin ang ai_model, topology, target_polycount, should_remesh, at save_pre_remeshed_model.
Name
ai_model
Type
string
default latest
Description
ID ng model na gagamitin. Nakadepende ang mga available na value 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: ang Smart Topology model — mas malinis na topology, likas na hiwalay na mga bahagi, triangle output, at isang face count na maitatakda mo gamit ang target_polycount.
- meshy-t2.5 (default): Mas matalas na detalye para sa mga game asset. Triangle output, at isang face count na maitatakda mo gamit ang target_polycount.
Name
geometry_resolution
Type
string
default standard
Description
Pass ng heometriya generation. 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
Kinakailangan 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_texture
Type
boolean
default true
Description
Tinutukoy kung gagawa ng mga texture. Ang pagtatakda nito sa false ay lumalaktaw sa texture phase, na nagbibigay ng mesh na walang texture.

Naaangkop lamang kapag should_texture = true

Name
enable_pbr
Type
boolean
default false
Description
Gumawa ng PBR Maps (metallic, roughness, normal) bilang karagdagan sa base color. Kasama rin ang emission map kapag ang ai_model ay meshy-6, maliban sa texture_resolution: 8k. Ang meshy-6-lite, meshy-7.1, meshy-t2 at latest ay hindi gumagawa ng emission map.
Name
texture_resolution
Type
string
default 2k
Description
Resolution ng base color texture. Isa sa 2k (2048×2048), 4k (4096×4096), o 8k (8192×8192). Ang mas mataas na resolution ay kumukuha ng mas maraming detalye ng ibabaw.
Hindi available ang 4k at 8k kasama ang ai_model na meshy-6-lite. Sa 8k, walang emission map na nabubuo.
Name
hd_texture
Type
boolean
⚠ lipas na
default false
Description
Gamitin ang texture_resolution sa halip — katumbas ng texture_resolution: "4k". Kapag pareho silang itinakda, mananaig ang texture_resolution.
Name
texture_prompt
Type
string
Description
Magbigay ng text prompt upang gabayan ang proseso ng pag-texture. Pinakamataas na 800 character.
Name
texture_image_url
Type
string
Description
Magbigay ng 2d na imahe upang gabayan ang proseso ng pag-texture. Kasalukuyan naming sinusuportahan ang mga format na .jpg, .jpeg, .png, at .webp.
Pinakamataas na laki ng file: 20 MB.
May dalawang paraan upang magbigay ng imahe:
- Publicly accessible URL: Isang URL na naa-access mula sa pampublikong internet
- Data URI: Isang base64-encoded data URI ng imahe. Halimbawa ng data URI: data:image/jpeg;base64,<your base64-encoded image data>
Maaaring hindi gumana nang optimal ang image texturing kung may malalaking pagkakaiba sa heometriya sa pagitan ng orihinal na asset at na-upload na imahe. Isa lamang sa texture_image_url o texture_prompt ang maaaring gamitin upang gabayan ang proseso ng pag-texture. Kung parehong parameter ay ibinigay, ang texture_prompt ang gagamitin bilang default upang i-texture ang model. Ang pag-texture sa pamamagitan ng teksto o imahe ay magkakakosto ng 10 credits kada task.

Name
should_remesh
Type
boolean
default false (Meshy 6 and Meshy 7 models), true (others)
Description
Kinokontrol kung ia-enable 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 ginawang model.
Mga available na value:
- quad: Gumawa ng quad-dominant na mesh.
- triangle: Gumawa ng decimated triangle mesh.
Triangle-only lamang ang output ng Smart Topology. Ang paghiling ng quad kasabay ng ai_model na meshy-t2 o meshy-t2.5 ay magbabalik ng error.
Name
decimation_mode
Type
integer
Description
I-enable ang adaptive decimation sa pamamagitan ng pagtatakda ng isang polycount level. Kapag itinakda, hindi papansinin 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
save_pre_remeshed_model
Type
boolean
default false
Description
Kapag itinakda sa true, nag-iimbak rin si Meshy ng karagdagang GLB file bago makumpleto ang remesh phase.

Name
target_polycount
Type
integer
Description
Target na bilang ng mga polygon (faces) sa output. Ang aktwal na bilang ay maaaring mag-iba sa target depende sa heometriya.
Nagkakabisa ang target_polycount sa dalawang independiyenteng kaso:
- Remesh — gamit ang should_remesh: true sa isang standard na model. Ang mesh ay nire-remesh (decimated) sa humigit-kumulang na bilang na ito. Saklaw 100 hanggang 300,000, default na 30,000. Kung itinakda ang decimation_mode, ito ang mananaig at hindi papansinin ang target_polycount.
- Smart Topology — gamit ang model_type: smart-topology at ai_model na meshy-t2 o meshy-t2.5. Direktang ginagawa ang model sa bilang ng face na ito; walang remesh na tumatakbo at hindi kinakailangan ang should_remesh. Para sa meshy-t2: saklaw 100 hanggang 15,000, default na 4,000. Para sa meshy-t2.5: saklaw 100 hanggang 30,000, default na 15,000.

Name
symmetry_mode
Type
string
⚠ lipas na
default auto
Description
Deprecated. Hindi na nakaaapekto ang parameter na ito sa output.
Kinokontrol ng field na symmetry_mode ang asal ng simetriya sa proseso ng paggawa ng model.
Ang mga valid na value ay:
- off: Dini-disable ang simetriya.
- auto: Awtomatikong tinutukoy at inilalapat ang simetriya batay sa input na heometriya.
- on: Pinipilit ang simetriya sa panahon ng paggawa.
Name
pose_mode
Type
string
default ""
Description
Tukuyin ang pose mode para sa ginawang model.
Mga available na value:
- a-pose: Gawin ang model sa A pose.
- t-pose: Gawin ang model sa T pose.
- "" (walang laman na 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 gagawin ang model sa A/T pose.
Name
surface_mode
Type
string
⚠ lipas na
Description
Hindi na nakaaapekto sa output. Pinili nito dati ang isang model generation na na-retire na; gamitin ang ai_model sa halip.
Ang mga tinatanggap na value ay organic at hard; magbabalik ng 400 ang anumang ibang value.
Name
image_enhancement
Type
boolean
default true
Description
Ino-optimize ang input image para sa mas magandang resulta. Itakda sa false upang panatilihin ang eksaktong hitsura ng input image nang walang anumang pagproseso ng istilo.
Sinusuportahan lamang kapag ang ai_model ay meshy-6, meshy-7.1, o latest. Ang pagtatakda nito kasama ng meshy-6-lite o model_type: smart-topology ay magbabalik ng error.
Name
remove_lighting
Type
boolean
default true
Description
Inaalis ang mga highlight at anino mula sa base color texture, na nagbubunga ng mas malinis na resulta na mas mahusay gumana sa ilalim ng custom na setup ng ilaw.
Nagkakabisa lamang kapag ang ai_model ay meshy-6. Tinatanggap ito ng meshy-7.1 at latest ngunit hindi pinapansin. Ang pagtatakda nito kasama ng meshy-6-lite o model_type: smart-topology ay magbabalik ng error.
Name
moderation
Type
boolean
default false
Description
Kapag itinakda sa true, awtomatikong susuriin ang input content para sa posibleng mapanganib na nilalaman. Kung may natuklasang mapanganib na nilalaman, hindi magpapatuloy ang task sa generation.
Ang nilalaman mula sa mga input na image_url, texture_image_url, at texture_prompt ay susuriin.
Name
target_formats
Type
string[]
Description
Tinutukoy kung aling mga 3D file format ang isasama sa output. Ang mga hiniling lamang na format ang gagawin at ibabalik, na maaaring magpabawas sa oras ng pagkumpleto ng task. Kapag tinanggal, lahat ng suportadong format ay isasama.
Mga available na value: glb, obj, fbx, stl, usdz, 3mf
Kapag tinanggal, lahat ng format maliban sa 3mf ay gagawin. Isasama lamang ang 3mf kapag tahasang tinukoy.
Name
auto_size
Type
boolean
default false
Description
Kapag itinakda sa true, ginagamit ng serbisyo ang AI vision upang awtomatikong tantyahin ang real-world na taas ng object at baguhin ang laki ng model nang naaayon. Ang origin ay magde-default sa bottom maliban kung tahasang itinakda ang origin_at.
Name
alpha_thumbnail
Type
boolean
default false
Description
Kapag itinakda sa true, karagdagang nagre-render ang task ng bersyon na may transparent-background (RGBA) ng preview at ibinabalik ito bilang alpha_thumbnail_url sa GET response. Hindi nagbabago ang umiiral na field na thumbnail_url.
Name
multi_view_thumbnails
Type
boolean
default false
Description
Kapag itinakda sa true, karagdagang nagre-render ang task ng apat na cardinal-view na thumbnail (harap, kanan, likod, kaliwa) at ibinabalik ang mga ito sa ilalim ng thumbnail_urls sa GET response. Hindi nagbabago ang umiiral na field na thumbnail_url at patuloy itong tumuturo sa front view, kaya hindi naaapektuhan ang mga umiiral na client.
Nagdadagdag ng humigit-kumulang 3 segundo sa latency ng task.

Naaangkop lamang kapag auto_size = true

Name
origin_at
Type
string
default bottom
Description
Posisyon ng origin kapag naka-enable ang auto_size.
Mga available na value: bottom, center.

Mga Ibabalik

Ang property na result ng response ay naglalaman ng task id ng bagong ginawang Image to 3D task.

Mga Mode ng Kabiguan

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang dahilan:
- Nawawalang parameter: Dapat ibigay ang alinman sa image_url o input_task_id.
- Di-wastong input task: Ang input_task_id ay dapat tumukoy sa isang SUCCEEDED na Text to Image o Image to Image task na gumagawa ng eksaktong isang imahe.
- Di-wastong format ng imahe: Ang ibinigay na image_url ay hindi isang suportadong format (.jpg, .jpeg, .png, .webp).
- Hindi maabot na URL: Hindi ma-download ang image_url (404 o timeout).
- Masyadong malaki ang imahe: Lumampas sa 20 MB ang imahe ng image_url o texture_image_url.
- Di-wastong Data URI: Malformed ang base64 string.
- Di-wastong kombinasyon ng parameter: Ang enable_pbr ay sinusuportahan lamang kapag true ang should_texture.
- Hindi suportadong model para sa low poly: Hindi sinusuportahan ng ai_model: "meshy-6-lite" ang model_type: "lowpoly".
- Hindi suportadong model para sa Ultra: Kailangan ng geometry_resolution ang meshy-7.1 o latest.
- Hindi suportadong model para sa mga opsyon ng imahe: Itinakda ang image_enhancement o remove_lighting kasama ng ai_model: "meshy-6-lite" o model_type: "smart-topology".
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat na credits upang maisagawa ang task na ito.
Name
429 - Too Many Requests
Description
Nalampasan mo na ang iyong rate limit.

Request

POST

/openapi/v1/image-to-3d

# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

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

GET/openapi/v1/image-to-3d/:id

Kunin ang isang Image to 3D Task

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

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa Image to 3D task na kukunin.

Ibinabalik

Ang tugon ay naglalaman ng Image to 3D task object. Tingnan ang seksyon The Image to 3D Task Object para sa mga detalye.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "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=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": 30
}

DELETE/openapi/v1/image-to-3d/:id

I-delete ang Image to 3D Task

Ang endpoint na ito ay permanenteng magde-delete ng Image to 3D task, kasama ang lahat ng kaugnay na modelo at datos. Hindi na maibabalik ang aksyong ito.

Path Parameters

Name
id
Type
path
Description
Ang ID ng Image to 3D task na ide-delete.

Status ng Task

Ang task na nasa PENDING pa ay made-delete at ang mga credits na nagastos noong create-time ay irerefund.

Ang task na IN_PROGRESS na ay hindi na made-delete: ang request ay tatanggihan na may 409 Conflict at ipagpapatuloy ng task ang pagtakbo. Ang mga credits para sa task na nasimulan na ng worker ay hindi na maibabalik, kaya kung ide-delete ito habang tumatakbo ay mawawala sa iyo ang credits at ang resulta. Hintayin na umabot ito sa SUCCEEDED, FAILED o CANCELED, bago ito i-delete.

Ang task na nasa terminal state (SUCCEEDED, FAILED o CANCELED) ay made-delete nang walang refund.

Mga Ibinabalik

Ibinabalik ang 200 OK kapag matagumpay, o 409 Conflict kapag ang task ay IN_PROGRESS.

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-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/v1/image-to-3d

List Image to 3D Tasks

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

Mga Parameter

Mga opsyonal na attribute

Name
page_num
Type
integer
Description
Numero ng pahina para sa pagination. Nagsisimula at nagde-default sa 1.
Name
page_size
Type
integer
Description
Limitasyon ng laki ng pahina. Nagde-default sa 10 na item. 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 sa pataas na pagkakasunod-sunod.
- -created_at: Pag-sort ayon sa oras ng paglikha sa pababang pagkakasunod-sunod.

Ibinabalik

Nagbabalik ng isang pinagination na listahan ng The Image to 3D Task Objects.

Request

GET

/openapi/v1/image-to-3d

curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "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=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "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": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

I-stream ang Image to 3D Task

Nagpapadala ang endpoint na ito ng real-time na mga update para sa isang Image to 3D task gamit ang Server-Sent Events (SSE).

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa Image to 3D task na i-stream.

Ibinabalik

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

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

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-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",
  "type": "image-to-3d",
  "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=***",
  "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=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": 30
}

The Image to 3D Task Object

Ang Image to 3D Task object ay isang work unit na sinusubaybayan ng Meshy para makabuo ng 3D model mula sa isang imahe na input. Ang object na ito ay may mga sumusunod na properties:

Properties

Name
id
Type
string
Description
Natatanging identifier para sa task. Bagama't gumagamit kami ng k-sortable UUID para sa task ids bilang detalye ng implementasyon, hindi ka dapat gumawa ng anumang palagay tungkol sa format ng id.
Name
type
Type
string
Description
Uri ng Image to 3D task. Ang value ay image-to-3d.
Name
model_urls
Type
object
Description
Downloadable URL patungo sa textured 3D model file na ginawa ng Meshy. Ang property para sa isang format ay aalisin kung hindi nabuo ang format sa halip na magbalik ng walang laman na string.
- Name
  glb
  Type
  string
  Description
  Downloadable URL patungo sa GLB file.
- Name
  fbx
  Type
  string
  Description
  Downloadable URL patungo sa FBX file.
- Name
  obj
  Type
  string
  Description
  Downloadable URL patungo sa OBJ file.
- Name
  usdz
  Type
  string
  Description
  Downloadable URL patungo sa USDZ file.
- Name
  mtl
  Type
  string
  Description
  Downloadable URL patungo sa MTL file, na ibinabalik kasama ng OBJ exports kapag may mga texture.
- Name
  stl
  Type
  string
  Description
  Downloadable URL patungo sa STL file.
- Name
  3mf
  Type
  string
  Description
  Downloadable URL patungo sa 3MF file. Lalabas lamang kapag hiniling ang 3mf sa pamamagitan ng target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Downloadable URL patungo sa orihinal na GLB output bago mag-remesh.
  Available lamang kapag ang task ay nagawa gamit ang parehong should_remesh: true at save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
Downloadable URL patungo sa thumbnail image ng model file. Katumbas ng thumbnail_urls.front kapag naroroon, pinananatili para sa backwards compatibility.
Name
alpha_thumbnail_url
Type
string
Description
Downloadable URL patungo sa bersyong transparent-background (RGBA) ng thumbnail_url. Lalabas lamang kapag ang task ay nagawa gamit ang alpha_thumbnail: true at matagumpay na na-render ang transparent preview; kung hindi, aalisin ang field na ito.
Name
thumbnail_urls
Type
object
Description
Downloadable URLs para sa apat na cardinal-view thumbnails ng nabuong 3D model. Ang bawat value ay isang signed URL patungo sa 512×512 PNG na na-render gamit ang parehong materials at lighting gaya ng thumbnail_url. Kapaki-pakinabang para sa pag-preview ng model mula sa maraming anggulo sa batch pipelines nang hindi kinakailangang i-download ang GLB.
Lalabas lamang kapag ang task ay nagawa gamit ang multi_view_thumbnails: true at naabot na ang SUCCEEDED. Ang mga lumang task at mga task na ginawa nang walang opt-in na ito ay hindi isasama ang field na ito.
- Name
  front
  Type
  string
  Description
  Front view, 0° rotation sa paligid ng vertical axis (tumutugma sa thumbnail_url).
- Name
  right
  Type
  string
  Description
  Right view, 90° rotation.
- Name
  back
  Type
  string
  Description
  Back view, 180° rotation.
- Name
  left
  Type
  string
  Description
  Left view, 270° rotation.
Name
texture_prompt
Type
string
Description
Ang text prompt na ginamit upang gabayan ang proseso ng pag-texture.
Name
texture_image_url
Type
string
Description
Downloadable URL patungo sa texture image na ginamit upang gabayan ang proseso ng pag-texture.
Name
ultra_mode
Type
boolean
⚠ lipas na
Description
Deprecated; basahin na lamang ang geometry_resolution.
Name
geometry_resolution
Type
string
Description
Ang Ultra tier na pinatakbo ng task (2k o 4k); aalisin para sa standard.
Name
progress
Type
integer
Description
Progress ng task. Kung hindi pa nagsisimula ang task, ang property na ito ay magiging 0. Kapag nagtagumpay na ang task, ito ay magiging 100.
Name
started_at
Type
timestamp
Description
Timestamp kung kailan sinimulan ang task, sa milliseconds. Kung hindi pa nagsisimula ang task, ang property na ito ay magiging 0.
Ang isang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas simula Enero 1, 1970 UTC, sinusunod ang pamantayang RFC 3339. Halimbawa, ang Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Ito ay naaangkop sa lahat ng timestamps sa Meshy API.
Name
created_at
Type
timestamp
Description
Timestamp kung kailan ginawa ang task, sa milliseconds.
Name
expires_at
Type
timestamp
Description
Timestamp kung kailan mag-e-expire ang resulta ng task, sa milliseconds.
Name
finished_at
Type
timestamp
Description
Timestamp kung kailan natapos ang task, sa milliseconds. Kung hindi pa tapos ang task, ang property na ito ay magiging 0.
Name
status
Type
string
Description
Status ng task. Ang mga posibleng value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Isang array ng texture URL objects na nabuo mula sa task. Karaniwan, isang (1) texture URL object lamang ang laman nito. Ang bawat texture URL ay may mga sumusunod na properties:
- Name
  base_color
  Type
  string
  Description
  Downloadable URL patungo sa base color map image.
- Name
  metallic
  Type
  string
  Description
  Downloadable URL patungo sa metallic map image.
  Kung ang task ay ginawa gamit ang enable_pbr: false, aalisin ang property na ito.
- Name
  normal
  Type
  string
  Description
  Downloadable URL patungo sa normal map image.
  Kung ang task ay ginawa gamit ang enable_pbr: false, aalisin ang property na ito.
- Name
  roughness
  Type
  string
  Description
  Downloadable URL patungo sa roughness map image.
  Kung ang task ay ginawa gamit ang enable_pbr: false, aalisin ang property na ito.
- Name
  emission
  Type
  string
  Description
  Downloadable URL patungo sa emission map image.
  Kung ang task ay ginawa gamit ang enable_pbr: false, o ang ai_model ay meshy-6-lite, meshy-7.1, meshy-t2, o latest, aalisin ang property na ito.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang task.
Ang value 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 nagamit ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga task na FAILED (ang credits ay ire-refund kapag nabigo).

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "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=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "texture_image_url": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": 30
}