Image to 3D API

Gawing 3D model ang isang imahe, may texture man o wala, sa mga format na iyong pipiliin. Ipadala ang imahe, o gamitin ang output ng isang Text to Image o Image to Image task.

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

Gumawa ng Image to 3D na gawain

Gumagawa ng Image to 3D na gawain. Tumatakbo ang gawain sa background. Para sa karaniwang tagal ng isang gawain, tingnan ang Processing times.

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

# Textured with Meshy N1 from the input image
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",
    "texture_model": "meshy-n1"
  }'

Response

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

Mga Parameter

Name
input_task_id
Type
string
Kinakailangan
Description
Kailangan maliban kung magpapadala ka ng image_url. Ang ID ng isang Text to Image o Image to Image na gawain na ang larawan ang gusto mong gamitin bilang input. Dapat ang gawaing ito ay ginawa mo gamit ang API, may status na SUCCEEDED, at nakagawa ng eksaktong isang larawan.

Name
image_url
Type
string
Kinakailangan
Description
Kailangan maliban kung magpapadala ka ng input_task_id. Ang larawang gagawing 3D model, bilang isang pampublikong URL o isang base64-encoded na data URI, tulad ng data:image/jpeg;base64,<your base64-encoded image data>. Kung ipapadala mo ang pareho, ginagamit ng Meshy ang input_task_id.
Dapat ang larawan ay isang JPG, JPEG, PNG, o WebP 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).

Name
model_type
Type
string
default standard
Description
Ang uri ng 3D mesh na gagawin.
Mga available na value:
- standard: isang mesh na mataas ang detalye
- smart-topology: isang mesh mula sa isang Smart Topology model, na pinipili mo gamit ang ai_model (meshy-t2 o meshy-t2.5)
Sa smart-topology, hindi pinapansin ng Meshy ang should_remesh, save_pre_remeshed_model, at decimation_mode, at tanging topology: triangle lamang ang tinatanggap.
Name
ai_model
Type
string
default latest
Description
Ang AI model na gumagawa ng 3D model. Ang mga available na value ay depende sa model_type.
Standard models (model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (deprecated): gamitin na lang ang meshy-7.1
Ang Smart Topology models (model_type: smart-topology) ay gumagawa ng mga triangle, sa isang face count na maaari mong itakda gamit ang target_polycount:
- meshy-t2: mas malinis na topology at likas na hiwalay na mga bahagi
- meshy-t2.5 (default): mas matalas na detalye para sa mga game asset
Name
geometry_resolution
Type
string
default standard
Description
Ang geometry generation pass.
Mga available na value:
- standard
- 2k: pinapatakbo ang Ultra pass sa 2048³
- 4k: pinapatakbo ang Ultra pass sa 4096³, para sa pinakamaraming detalye sa ibabaw
Kailangan ng 2k ang meshy-7.1, latest, o ang deprecated na meshy-7. Kailangan ng 4k ang meshy-7.1 o latest.
Name
ultra_mode
Type
boolean
⚠ lipas na
default false
Description
Gamitin na lang ang geometry_resolution. Ang ultra_mode: true ay katumbas ng geometry_resolution: "2k".
Name
should_texture
Type
boolean
default true
Description
Kung gagawa ng mga texture. Ang true ay nagbabalik ng isang may-texture na model, at ang false ay nilalaktawan ang pag-te-texture at nagbabalik ng isang walang-texture na mesh.

Naaangkop lamang kapag should_texture = true

Name
texture_model
Type
string
default depends on ai_model
Description
Ang AI model na nag-te-texture sa 3D model, sa parehong gawain. Iwanan itong wala para gamitin ang default texture model para sa iyong ai_model. Hindi nito binabago ang halaga ng credits.
Mga available na value:
- meshy-7: Meshy 7, na may PBR maps at mga texture na hanggang 8K
- meshy-n1: Meshy N1, isang 2K base color texture mula lamang sa mga reference image
- meshy-6-lite: Meshy 6 Lite, isang 2K texture sa pinakamababang halaga
- meshy-6: Meshy 6, tanging bilang default lamang para sa ai_model: meshy-6
Tinatanggap ng bawat ai_model ang meshy-7, meshy-n1, at meshy-6-lite. Ang isang option na hindi suportado ng napiling texture model ay nagbabalik ng 400. Sa meshy-n1, isang nagawang model na higit sa 7,999,999 triangles ay nabibigo ang gawain, at nire-refund ng Meshy ang mga credits nito. Sa should_texture: false, hindi pinapansin ng Meshy ang texture_model, pero ang isang hindi-kilalang value ay nagbabalik pa rin ng 400.
Tingnan ang Models para sa kung ano ang ginagawa ng bawat texture model at kung alin ang piliin.
Name
enable_pbr
Type
boolean
default false
Description
Kung gagawa rin ng PBR maps (metallic, roughness, at normal) bukod sa base color. Kailangan ng true ang should_texture: true, at nagbabalik ng 400 sa should_texture: false. Sa texture_model: meshy-n1, ang true ay nagbabalik ng 400.
Gumagawa rin ng emission map ang Meshy 6 texture model, maliban sa texture_resolution: 8k.
Name
texture_resolution
Type
string
default 2k
Description
Ang laki ng base color texture. Mas malaking texture ang kumukuha ng mas maraming detalye sa ibabaw.
Mga available na value:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Kailangan ng 4k at 8k ang Meshy 7 o Meshy 6 texture model, at nagbabalik ng 400 sa iba. Sa 8k, hindi gumagawa ang Meshy ng emission map.
Name
hd_texture
Type
boolean
⚠ lipas na
default false
Description
Gamitin na lang ang texture_resolution. Ang hd_texture: true ay katumbas ng texture_resolution: "4k". Kung ipapadala mo ang pareho, ginagamit ng Meshy ang texture_resolution.
Name
texture_prompt
Type
string
Description
Tekstong gumagabay sa texture, hanggang 800 character. Ang mas mahabang teksto ay nagbabalik ng 400. Sa texture_model: meshy-n1, ang pagpapadala nito ay nagbabalik ng 400.
Name
texture_image_url
Type
string
Description
Isang larawang gumagabay sa texture, bilang isang pampublikong URL o isang 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 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).
Gumagabay lamang ang Meshy sa texture gamit ang isa sa texture_prompt at texture_image_url. Kung ipapadala mo ang pareho, ginagamit ng Meshy ang texture_prompt. Para sa halaga ng credits ng pag-te-texture, tingnan ang Pricing.
Sa texture_model: meshy-n1, nagte-texture ang Meshy mula sa larawang ito bilang front view, o mula sa input image kung iiwanan mo itong wala.
Maaaring hindi gumana nang maayos ang pag-te-texture mula sa isang larawan kapag malaki ang pagkakaiba ng hugis ng larawan sa heometriya ng 3D model.

Name
should_remesh
Type
boolean
default true (meshy-6-lite), false (other models)
Description
Kung patatakbuhin ang remesh phase. Para sa pinakamataas na kalidad ng 3D model, itakda ito sa false.

Naaangkop lamang kapag should_remesh = true

Name
topology
Type
string
default triangle
Description
Ang face type ng na-remesh na model.
Mga available na value:
- quad: isang mesh na mas maraming quad
- triangle: isang pinaliit na triangle mesh
Tanging triangle lamang ang output ng Smart Topology, kaya ang quad na may meshy-t2 o meshy-t2.5 ay nagbabalik ng 400. Sa texture_model: meshy-n1, ang quad ay nagbabalik ng 400 kapag na-remesh ang model, na siyang ginagawa ng meshy-6-lite bilang default.
Name
decimation_mode
Type
integer
Description
Adaptive face count, ayon sa antas. Kapag itinakda mo ito, hindi pinapansin ng Meshy ang target_polycount.
Mga available na value:
- 1: ultra
- 2: high
- 3: medium
- 4: low
Name
save_pre_remeshed_model
Type
boolean
default false
Description
Kung mag-iimbak rin ng GLB ng model mula bago ang remesh phase. Ibinabalik ito ng Meshy sa model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
Ang bilang ng mga face na gagawing target. Maaaring iba ang resulta kumpara sa target, depende sa heometriya ng model.
Nalalapat ito sa dalawang hiwalay na kaso:
- Remesh: Kapag true ang should_remesh sa isang standard na model, pinaliliit ng Meshy ang mesh sa humigit-kumulang sa bilang na ito. Kung itatakda mo ang decimation_mode, ginagamit ito ng Meshy at hindi pinapansin ang target_polycount.
- Smart Topology: Kapag ang model_type ay smart-topology at ang ai_model ay meshy-t2 o meshy-t2.5, ginagawa ng Meshy ang model sa face count na ito. Walang tumatakbong remesh, at hindi mo kailangan ang should_remesh.
Ang saklaw at default ay depende sa 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 nagbabalik 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
Iwanan itong wala, dahil hindi nito naaapektuhan ang output. Kinokontrol ng mga value nito ang simetriya habang gumagawa:
- off: walang simetriya
- auto: simetriyang pinili mula sa input geometry
- on: ipinapatupad na simetriya
Name
pose_mode
Type
string
default ""
Description
Ang pose para sa nagawang model.
Mga available 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
Gamitin na lang ang pose_mode. Kung gagawin ang model sa A o T pose.
Name
surface_mode
Type
string
⚠ lipas na
Description
Gamitin na lang ang ai_model. Hindi nito naaapektuhan ang output, dahil retirado na ang model generation na pinili nito.
Ang mga tinatanggap na value ay organic at hard. Ang anumang ibang value ay nagbabalik ng 400.
Name
image_enhancement
Type
boolean
default true
Description
Kung i-oopimize ang input image bago gumawa. Ang false ay pinapanatili ang eksaktong itsura ng input image, nang walang pagpoproseso ng estilo.
Gumagana lamang ito sa meshy-6, meshy-7.1, o latest. Sa meshy-6-lite o model_type: smart-topology, nagbabalik ito ng 400.
Name
remove_lighting
Type
boolean
default true
Description
Kung aalisin ang mga highlight at anino mula sa base color texture. Mas malinis ang resulta at mas gumagana nang maayos sa iyong sariling lighting.
Nagkakabisa lamang ito sa Meshy 6 texture model, at ang isang texture model na hindi ito sinusuportahan ay nagbabalik ng 400 para sa true. Sa model_type: smart-topology, o sa ai_model: meshy-6-lite at ang default texture model nito, ang pagpapadala nito ay nagbabalik ng 400.
Name
moderation
Type
boolean
default false
Description
Kung sususuriin ang mga input na ito para sa nakakapinsalang nilalaman bago gumawa:
- image_url
- texture_image_url
- texture_prompt
Kung makakita ang Meshy ng nakakapinsalang nilalaman, ang request ay nagbabalik ng 400 at hindi gumagawa ng gawain ang Meshy.
Name
target_formats
Type
string[]
Description
Ang mga format ng file na gagawin. Gumagawa at nagbabalik lamang ang Meshy ng mga format na nakalista mo, na maaaring magpaikli sa gawain. Kung iiwanan mo itong wala, gumagawa ang Meshy ng bawat format maliban sa 3mf, na makukuha mo lamang kung ilista mo ito.
Mga available na value:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
default false
Description
Kung tatantiyahin ang tunay na taas ng bagay sa totoong mundo gamit ang AI vision at papalitan ang sukat ng model dito. Inilalagay ng Meshy ang origin sa ibaba maliban kung itatakda mo ang origin_at.
Name
alpha_thumbnail
Type
boolean
default false
Description
Kung mag-rerender din ng preview na may transparent background (RGBA), na ibinabalik sa alpha_thumbnail_url kapag kinuha mo ang gawain. Hindi nagbabago ang thumbnail_url.
Name
multi_view_thumbnails
Type
boolean
default false
Description
Kung mag-rerender din ng mga preview sa harap, kanan, likod, at kaliwa, na ibinabalik sa thumbnail_urls kapag kinuha mo ang gawain. Hindi nagbabago ang thumbnail_url at ipinapakita pa rin nito ang front view. Nagdaragdag ito ng mga 5 segundo sa gawain.

Naaangkop lamang kapag auto_size = true

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

Mga Ibinabalik

Ang result field ng tugon ay naglalaman ng ID ng bagong Image to 3D na gawain.

Mga Paraan ng Pagkabigo

Name
400 - Bad Request
Description
Hindi matatakbo ang request. Sinasabi ng error message kung aling problema ang nakita nito. Halimbawa:
- Missing parameter: Walang ipinadala sa image_url o input_task_id.
- Invalid input task: Ang input_task_id ay hindi isang SUCCEEDED na Text to Image o Image to Image na gawain na nakagawa ng eksaktong isang larawan.
- Invalid image format: Ang larawan ng image_url ay hindi isang JPG, JPEG, PNG, o WebP file.
- Unreachable URL: Hindi ma-download ng Meshy ang larawan ng image_url, dahil ang URL ay nagbabalik ng 404 o nag-ti-timeout.
- Image too large: Ang larawan ng image_url o texture_image_url ay higit sa 20 MB.
- Invalid image size: Ang larawan ng image_url o texture_image_url ay may gilid na mas maikli sa 32 pixels, o higit sa 178,956,970 pixels (lapad × taas).
- Invalid data URI: Ang base64 string ay malformed.
- Invalid parameter combination: true ang enable_pbr, at false ang should_texture.
- Unsupported model for Ultra: 2k o 4k ang geometry_resolution, na may ai_model na hindi ito mapapatakbo.
- Unsupported model for image options: isa sa mga ito:
  - Ipinadala ang image_enhancement na may ai_model: "meshy-6-lite" o model_type: "smart-topology".
  - Ipinadala ang remove_lighting na may model_type: "smart-topology", o may ai_model: "meshy-6-lite" at ang default texture model nito.
- Invalid texture model: Ang texture_model ay hindi isa sa mga available na value.
- Texture model not available: Ang texture_model ay meshy-6 na may ai_model na iba sa meshy-6. Magpadala ng meshy-7, meshy-n1, o meshy-6-lite, o iwanan itong wala.
- Unsupported option for the texture model: Humihiling ang request sa texture model ng isang option na hindi nito sinusuportahan, tulad ng enable_pbr: true na may meshy-n1 o isang 4k na texture na may meshy-6-lite. Tingnan ang Models.
Ayusin ang request, pagkatapos ay ipadala itong muli. 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 gawaing ito, o naabot na ng account ang limitasyon ng credits. Suriin ang iyong credit balance, pagkatapos ay subukan muli.
- Free plan: Nangangailangan ng bayad na plano ang paggawa ng gawain. I-upgrade ang iyong plano sa iyong mga setting ng subscription, pagkatapos ay subukan muli.
Name
403 - Forbidden
Description
Hinarang ng content moderation ang prompt o isang input image. Baguhin ang input, pagkatapos ay subukan muli.
Name
404 - Not Found
Description
Hindi tumutugma ang input_task_id sa alinman sa iyong mga gawain. Suriin ang task ID, pagkatapos ay ipadala ang request muli.
Name
429 - Too Many Requests
Description
Nalampasan mo ang iyong rate limit. Maghintay, pagkatapos ay subukan muli. Tingnan ang Rate limits.

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

Kunin ang gawain ng Image to 3D

Ibinabalik ang isang gawain ng Image to 3D ayon sa ID nito.

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": null,
  "consumed_credits": 30
}

Mga Parameter

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

Ibinabalik

Ang Image to 3D task object.

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

Mag-delete ng Image to 3D task

Permanenteng nagde-delete ng Image to 3D task, kasama ang mga model at data nito. Hindi na maibabalik ang pag-delete.

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 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 ide-delete.

Status ng task

Kapag nag-delete ka ng PENDING na task, naire-refund ang mga credits na nagamit noong ginawa mo ito.

Hindi maaaring i-delete ang isang IN_PROGRESS na task. Magbabalik ang request ng 409 Conflict, at magpapatuloy ang pagtakbo ng task. Hindi nagre-refund si Meshy para sa isang task na nagsimula na, kaya kung ide-delete mo ito, mawawala sa iyo ang parehong credits at resulta. Hintayin itong umabot sa SUCCEEDED, FAILED, o CANCELED, bago mo ito i-delete.

Ang pag-delete ng task na nasa huling status na (SUCCEEDED, FAILED, o CANCELED) ay hindi nagre-refund ng mga credits nito.

Mga ibinabalik

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

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

List Image to 3D tasks

Nagbabalik ng listahan ng iyong mga Image to 3D tasks.

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": null,
    "consumed_credits": 30
  }
]

Mga Parameter

Name
page_num
Type
integer
default 1
Description
Ang bilang ng pahina na ibabalik, hanggang 255. Ang mas malaking value ay magbabalik ng 400.
Name
page_size
Type
integer
default 10
Description
Ang bilang ng mga task kada pahina, hanggang 100.
Name
sort_by
Type
string
Description
Ang pagkakaayos ng pag-uuri.
Mga available na value:
- +created_at: pinakaluma muna
- -created_at: pinakabago muna

Ibinabalik

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

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

I-stream ang isang Image to 3D task

Nagsa-stream ng mga update ng isang Image to 3D task bilang Server-Sent Events (SSE).

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.
// 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",
  "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": null,
  "consumed_credits": 30
}

Mga Parameter

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

Ibinabalik

Isang stream ng Image 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 value ang mga result field nito.

The Image to 3D task object

Ang Image to 3D task object ay naglalarawan ng isang pagbuo ng 3D model mula sa isang larawan. Nilalaman nito ang status, ang progress, at ang mga file ng model kapag nagtagumpay ang task.

Mga Property

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": null,
  "consumed_credits": 30
}

Name
id
Type
string
Description
Ang task ID. Ituring itong isang opaque na string, at huwag umasa sa format nito.
Name
type
Type
string
Description
Ang uri ng task, palaging image-to-3d.
Name
model_urls
Type
object
Description
Mga download URL para sa nabuong 3D model, isa bawat file format. Ang format na hindi nabuo 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
  obj
  Type
  string
  Description
  Ang OBJ file.
- Name
  usdz
  Type
  string
  Description
  Ang USDZ file.
- Name
  mtl
  Type
  string
  Description
  Ang MTL file, na ibinabalik kasama ng OBJ file kapag may mga texture ang model.
- Name
  stl
  Type
  string
  Description
  Ang STL file.
- Name
  3mf
  Type
  string
  Description
  Ang 3MF file. Naroroon lamang kapag kasama sa target_formats ang 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Ang GLB file bago ang remesh. Naroroon lamang kapag ginawa mo ang task gamit ang parehong should_remesh: true at save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
Download URL para sa isang preview na larawan ng 3D model. Kapag naroroon ang thumbnail_urls, ito ay kaparehong larawan ng thumbnail_urls.front. Pinapanatili ito ni Meshy para sa backward compatibility.
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
thumbnail_urls
Type
object
Description
Mga download URL para sa mga preview ng 3D model mula sa apat na panig. Ang bawat value ay isang naka-sign na URL patungo sa isang 512×512 PNG, na na-render gamit ang parehong mga materyal at ilaw gaya ng thumbnail_url. Gamitin ang mga ito para i-preview ang model mula sa iba't ibang anggulo, halimbawa sa isang batch pipeline, nang hindi kinakailangang i-download ang GLB.
Naroroon lamang kapag ginawa mo ang task gamit ang multi_view_thumbnails: true at umabot ang task sa SUCCEEDED. Ang mga task na ginawa nang walang multi_view_thumbnails: true ay hindi kasama ang field na ito.
- Name
  front
  Type
  string
  Description
  Ang harapang view, sa 0° paikot sa patayong axis. Ito ay tumutugma sa thumbnail_url.
- Name
  right
  Type
  string
  Description
  Ang kanang view, sa 90°.
- Name
  back
  Type
  string
  Description
  Ang likurang view, sa 180°.
- Name
  left
  Type
  string
  Description
  Ang kaliwang view, sa 270°.
Name
texture_prompt
Type
string
Description
Ang text prompt na gumabay sa texture.
Name
texture_image_url
Type
string
Description
Download URL para sa larawan na gumabay sa texture.
Name
ultra_mode
Type
boolean
⚠ lipas na
Description
Basahin na lamang ang geometry_resolution.
Name
geometry_resolution
Type
string
Description
Ang Ultra tier kung saan tumakbo ang task, 2k o 4k. Ang isang standard na task ay hindi kasama ang field na ito.
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 nalikha ang task, sa Unix milliseconds.
Name
expires_at
Type
timestamp
Description
Oras na mag-e-expire ang resulta ng 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
Ang mga texture map na nabuo ng task, bilang isang array ng mga object. Karaniwan itong naglalaman ng isang object, na may mga sumusunod na field:
- Name
  base_color
  Type
  string
  Description
  Download URL para sa base color map.
- Name
  metallic
  Type
  string
  Description
  Download URL para sa metallic map. Wala ang field na ito kapag ginawa mo ang task gamit ang enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Download URL para sa normal map. Wala ang field na ito kapag ginawa mo ang task gamit ang enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Download URL para sa roughness map. Wala ang field na ito kapag ginawa mo ang task gamit ang enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Download URL para sa emission map. Isinasama ito ni Meshy lamang kapag ginawa mo ang task gamit ang lahat ng mga sumusunod:
  
  ai_model: meshy-6, kasama ang default na texture model nito
  
  enable_pbr: true
  
  isang texture_resolution na 2k o 4k
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga task na nauuna sa task na ito sa queue. Makabuluhan lamang ang value habang ang task ay PENDING.
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.