Paano Gamitin ang Image to 3D Model API: Isang Kumpletong Gabay 2026

Ang Image to 3D Model API ay ginagawang production-ready 3D model sa ilang segundo ang isang larawan—nang walang manu-manong pagmomodelo. Ang manu-manong pagmomodelo ng bawat asset ay mabagal at magastos, at para sa mga game studio, AR app, at e-commerce team, mabilis itong nagiging bottleneck na nagpapaantala sa mga paglulunsad. Inaalis ng Meshy's image-to-3D model API ang hadlang na iyon: magpadala ng larawan, i-convert ito sa 3D model sa ilang segundo, at i-download ang isang ganap na naka-texture na mesh sa mga format tulad ng GLB, FBX, at OBJ. Ang gabay na ito ay magtuturo sa iyo sa buong workflow—mula sa paggawa ng iyong API key hanggang sa pag-download ng iyong unang modelo—na may copy-paste code na maaari mong patakbuhin sa ilang minuto.

Ano ang Image to 3D Model API?

Sa kaibuturan nito, ang Image to 3D Model API ay isang REST endpoint na pinapagana ng Meshy's image to 3D model AI. Nagpapadala ka ng isang larawan (JPG, JPEG, o PNG) bilang isang pampublikong URL o base64 string, at ang API ay nagbabalik ng isang textured 3D model—kasama ang geometry at base color textures—sa mga karaniwang format tulad ng GLB, FBX, OBJ, USDZ, STL, at 3MF. Kasama sa mga opsyonal na add-on ang PBR maps, hanggang 4K na texture, at multi-angle preview thumbnails.

Pinapagana ng aming pinakabagong Meshy 6 model, pinapayagan ka ng API na i-configure ang topology at polygon counts, mag-set ng pose modes, at gabayan ang texturing gamit ang isang text prompt o reference image—perpekto para sa pagbuo ng mga asset para sa mga laro, AR/VR, 3D printing, at product visualization.

Ano ang kailangan mo para magamit ang Image to 3D API?

Hindi mo kailangan ng marami para sundin ang gabay na ito. Siguraduhing mayroon ka ng:

• Isang Meshy account — mag-sign up nang libre kung wala ka pa. Bubuo ka ng iyong API key mula sa dashboard sa Step 1.

• Isang API key — ginagamit para i-authenticate ang bawat request. Tatalakayin natin ang paggawa nito, at maaari mong gamitin ang libreng test mode key para sumunod nang hindi gumagamit ng credits.

• Isang input image — isang malinaw na .jpg, .jpeg, o .png na naka-host sa isang pampublikong accessible na URL (o naka-encode bilang base64). Ang isang malinis na background at isang malinaw na nakikitang subject ay nagbibigay ng pinakamahusay na resulta.

• Isang paraan para gumawa ng HTTP requests — curl (ginamit sa mga halimbawa sa ibaba), Postman, o anumang HTTP library sa iyong napiling wika. Ang pangunahing kaalaman sa REST APIs at JSON ay nakakatulong ngunit hindi kinakailangan.

Iyon lang—walang kailangan na karanasan sa 3D modeling. Magsimula na tayo.

Paano I-convert ang isang Larawan sa isang 3D Model gamit ang API (Step-by-Step na Gabay)

Step 1: I-set Up ang Iyong Mga Setting ng API

Lahat ng kailangan mo para simulan ang pagbuo ay nasa pahina ng mga setting ng API. Ito ang iyong control center para sa Meshy API, at mayroon itong tatlong pangunahing seksyon:

• API Keys — bumuo at pamahalaan ang mga key na nag-a-authenticate sa iyong mga request.

• Webhooks — maabisuhan nang awtomatiko kapag natapos na ang iyong mga gawain.

• Usage — subaybayan ang iyong natitirang credit balance at API consumption sa real time.

Talakayin natin ang bawat isa.

Kunin ang Iyong API Key

Bago gumawa ng anumang request, kailangan mo ng API key para ligtas na mag-authenticate. Sa pahina ng mga setting ng API, i-click ang Generate API Key. Bawat key ay sumusunod sa format na msy-<random-string>.

Tip: Kapag nabuo na, itago ang iyong API key sa isang secure na lugar (hal., isang password manager o environment variable). Tratuhin ito tulad ng isang password—huwag kailanman i-commit ito sa source control o ilantad sa client-side code.

Test Mode API Key

Sa panahon ng development at testing, maaari mong gamitin ang test mode API key upang galugarin ang API nang hindi gumagamit ng iyong mga credits:

msy_dummy_api_key_for_test_mode_12345678

Ang espesyal na key na ito ay may mga sumusunod na katangian:

• Maaari itong gamitin upang gumawa ng mga request sa lahat ng Meshy API endpoints.

• Walang credits ang nauubos kapag ginagamit ang key na ito.

• Lahat ng valid na request ay nagbabalik ng parehong sample task result, anuman ang input parameters.

• Ang istraktura ng response data ay eksaktong tumutugma sa production API.

Ginagawa nitong perpekto para sa pagsubok ng iyong integration bago lumipat sa iyong tunay na API key.

I-set Up ang Webhooks (Opsyonal)

Ang pagbuo ng 3D model ay tumatagal ng oras, kaya sa halip na paulit-ulit na i-poll ang API para tingnan kung tapos na ang isang gawain, maaari mong hayaang abisuhan ka ng Meshy sa sandaling matapos ito. Iyan ang gamit ng webhooks.

Sa seksyong Webhooks ng pahina ng mga setting, magdagdag ng endpoint URL kung saan dapat magpadala ang Meshy ng mga event notification. Kapag nagbago ang status ng isang gawain (halimbawa, kapag natapos o nabigo ito), magpapadala ang Meshy ng HTTP POST request sa iyong URL kasama ang mga detalye ng gawain sa payload.

Tip: Ang mga webhook ay ang inirerekomendang diskarte para sa production. Binabawasan nila ang mga hindi kinakailangang API call at pinapayagan ang iyong application na tumugon sa mga resulta sa real time. Para sa mabilis na pagsubok, gumagana pa rin ang polling. Upang subukan ang webhook code nang lokal, ituro ito sa isang proxy URL mula sa isang serbisyo tulad ng smee.io.

Subukan Ito Nang Walang Code — API Playground (Opsyonal)

Mayroon ka na bang API Key? Bago magsulat ng anumang code, maaari kang magpatakbo ng isang tunay na Image to 3D task nang direkta sa iyong browser.

Buksan ang meshy.ai/api-playground, piliin ang Image to 3D mula sa kaliwang panel, at punan ang tatlong bagay:

1. Authorization — i-paste ang iyong API Key (msy-xxxxxxxxxx)

2. Image — mag-upload ng .jpg, .jpeg, o .png mula sa iyong computer

3. Pindutin ang Send

Awtomatikong isinusumite ng Playground ang gawain at nagpo-poll para sa mga resulta. Kapag tapos na, makikita mo ang 3D model preview at mga download link nang direkta sa browser — walang code na kailangan.

Pro tip: Ang raw request/response panel sa kanan ay nagpapakita nang eksakto kung ano ang ipinapadala at ibinabalik ng API. Maaari mong kopyahin ang content nang direkta — kunin ang task_id mula sa response, at ang model_urls kapag natapos na ang gawain. Gagamitin mo ang dalawa sa mga susunod na hakbang.

Step 2: Magsumite ng Image to 3D Task

Sa iyong API key na handa, simulan ang isang gawain gamit ang isang POST request:

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

Makakatanggap ka ng tugon tulad nito:

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

Ang value na result ay ang iyong task_id — i-save ito. Kakailanganin mo ito sa susunod na hakbang upang suriin ang progreso at makuha ang iyong modelo.

Opsyonal: Upang maabisuhan nang awtomatiko kapag natapos na ang gawain, magdagdag ng field na webhook_url sa JSON body—halimbawa "webhook_url": "https://yourapp.com/webhooks/meshy". Tingnan ang Step 3, Option B para sa kung paano ito gumagana.

Step 3: Kunin ang Iyong Mga Resulta

Ang iyong gawain ay hindi natatapos kaagad—pinoproseso ito ng Meshy sa background. Mayroon kang dalawang paraan upang makuha ang resulta:

Option A: Mag-poll para sa Status (Pinakasimple)

Magpadala ng GET request tuwing 5 segundo hanggang ang status ay magbago sa SUCCEEDED:

curl https://api.meshy.ai/openapi/v1/image-to-3d/{task_id} \
  -H "Authorization: Bearer $MESHY_API_KEY"

Ang tugon ay ganito ang hitsura:

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

Ilang field na dapat malaman:

• model_urls ay naglalaman ng download link para sa bawat nabuong format. Bilang default, kasama dito ang glb, fbx, obj, usdz, stl, at mtl (ang material file na kasama ng obj).

• model_url ay isang shortcut sa GLB link—madaling gamitin kapag GLB lang ang kailangan mo.

• consumed_credits ay nagpapakita kung ilang credits ang ginamit ng gawain (ito ay 0 para sa mga nabigong gawain, dahil ang mga credits ay ibinabalik).

• thumbnail_url ay laging naroroon at tumuturo sa front-view thumbnail.

• thumbnail_urls ay lilitaw lamang kapag multi_view_thumbnails: true, at naglalaman ng front, right, back, at left views.

• alpha_thumbnail_url ay lilitaw lamang kapag alpha_thumbnail: true, at naglalaman ng transparent-background thumbnail.

Mga posibleng status value: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Option B: Webhook (Inirerekomenda para sa Production)

Kung nag-set ka ng webhook_url sa Step 2, awtomatikong magpo-POST ang Meshy ng natapos na task object sa iyong URL—walang polling na kailangan.

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 Alin ang dapat kong gamitin? Ang polling ay mainam para sa prototyping at isang beses na gawain. Gumamit ng webhooks sa production — mas maaasahan ito at nakakatipid ng mga API call.

Step 4: I-download ang Iyong 3D Model

Kapag ang status ay SUCCEEDED, kunin ang mga download URL mula sa model_urls at i-download ang format na kailangan mo:

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

Ang flag na -o model.glb ay nagse-save ng file sa iyong kasalukuyang working directory sa ilalim ng pangalang iyon—gumamit ng buong path (hal. -o /path/to/model.glb) upang i-save ito sa ibang lugar.

Bilang default, ang bawat gawain ay nagbabalik ng GLB, FBX, OBJ, USDZ, STL, at MTL (ang material file para sa OBJ). Ang 3MF ay opt-in—makukuha mo lamang ito kapag tahasan mong hiniling ito sa pamamagitan ng target_formats (tingnan ang talahanayan ng mga parameter sa ibaba).

⚠️ Ang mga link ay mag-e-expire sa loob ng 3 araw (ang mga Enterprise plan ay nakakakuha ng permanenteng link). I-download at iimbak ang iyong mga modelo kaagad — ang mga link ay hindi gagana pagkatapos ng expiry, at kakailanganin mong patakbuhin muli ang gawain.

Handa nang gamitin ang modelong ito sa iyong DCC tool? Tingnan ang gabay na Bridge to Blender—ang Meshy ay mayroon ding mga bridge para sa Unity, Unreal, Maya, at iba pa.

Paano makakuha ng pinakamahusay na image-to-3D na resulta?

• Gumamit ng isang solong, malinaw na nakikitang subject. Ang isang pangunahing bagay, naka-center at ganap na nasa frame, ay nagbibigay sa AI ng pinakamalinis na reference—iwasan ang mga abalang eksena, matinding pag-crop, at matinding anggulo.

• Mas gusto ang isang malinis, hindi kalat na background. Ang solid o simpleng background ay tumutulong sa modelo na ihiwalay ang subject mula sa paligid nito.

• Gumamit ng pantay, diffuse na ilaw. Ang matinding anino at malakas na highlight ay maaaring mag-bake ng mapanlinlang na detalye sa nabuong texture.

• Magsimula sa isang high-resolution, matalas na imahe. Mas maraming detalye sa input ay katumbas ng mas maraming detalye sa output—ang malabo o mababang resolution na input ay gumagawa ng mas malambot na mga modelo.

Aling mga programming language ang maaari kong gamitin sa Image to 3D API?

Anumang wika na maaaring gumawa ng HTTP requests—magpapadala ka ng POST na may JSON at magpo-poll gamit ang GET. Mga karaniwang opsyon:

• Python — gamitin ang requests o httpx library

• JavaScript / TypeScript — gamitin ang fetch (built-in) o axios

• Go — gamitin ang net/http mula sa standard library

• cURL — mahusay para sa mabilis na pagsubok mula sa terminal

Makakahanap ka rin ng mga ready-to-copy code sample para sa lahat ng apat sa API Playground.

Ilang credits ang halaga ng isang Image to 3D task?

Ang halaga ay depende sa bersyon ng modelo at kung bubuo ka ng mga texture. Ang default na setup (meshy-6 na may texturing) ay nagkakahalaga ng 30 credits bawat gawain:

Ang mga nabigong gawain ay awtomatikong binabalik ang credits—ang consumed_credits ay nagbabalik ng 0. Palaging suriin ang Pricing para sa pinakabagong mga rate.

Anong mga parameter ang tinatanggap ng Image to 3D API?

Magpadala ng POST sa /openapi/v1/image-to-3d gamit ang mga parameter na ito: Kinakailangan (isa sa):

Opsyonal:

Mga susunod na hakbang gamit ang Image to 3D API

Mayroon ka na ngayong kumpletong workflow: gumawa ng API key, magsumite ng larawan, mag-poll o gumamit ng webhook para sa resulta, pagkatapos ay i-download ang iyong modelo. Ang parehong apat na hakbang ay lumalaki mula sa isang mabilis na prototype hanggang sa isang production pipeline na awtomatikong ginagawang 3D asset ang libu-libong larawan. Kunin ang iyong key mula sa pahina ng mga setting ng API at i-ship ang iyong unang modelo ngayon. Mas gusto mong magsimula mula sa isang prompt sa halip na isang larawan? Gamitin ang Text to 3D Model API.

Mga Madalas Itanong

Paano ko iko-convert ang isang larawan sa isang 3D model sa pamamagitan ng API?

Magpadala ng POST request sa /openapi/v1/image-to-3d kasama ang iyong image_url at API key, pagkatapos ay i-poll ang gawain (o gumamit ng webhook) hanggang ang status nito ay SUCCEEDED. Ang response ay nagbabalik ng mga download link para sa nabuong modelo. Ang buong apat na hakbang na daloy—key, submit, retrieve, download—ay sakop sa step-by-step na gabay sa itaas.

Anong mga output format (STL, GLB, OBJ) ang sinusuportahan ng API?

Bawat gawain ay nagbabalik ng GLB, FBX, OBJ, USDZ, STL, at MTL bilang default, kasama ang 3MF na available kapag hiniling sa pamamagitan ng target_formats. Ang GLB ay pinakamahusay para sa web at AR, ang FBX at OBJ para sa DCC tools at game engine, ang USDZ para sa iOS AR, at ang STL para sa 3D printing.

Anong mga format ng larawan ang maaari kong i-upload?

Ang Image to 3D API ay sumusuporta sa JPG, JPEG, at PNG na mga larawan hanggang 100 MB—mas malaki kaysa sa 20 MB na limitasyon sa Meshy Workspace UI. Para sa pinakatumpak na resulta, gumamit ng PNG na may transparent o malinis na puting background, na tumutulong sa API na ihiwalay ang subject at bumuo ng mas mataas na kalidad na 3D model.

Maaari ba akong makakuha ng textured 3D model mula sa API?

Oo. Ang texturing ay naka-enable bilang default ("should_texture": true). Upang magdagdag ng PBR maps (metallic, roughness, normal), itakda ang "enable_pbr": true—sa meshy-6/latest kasama rin dito ang emission map. Para sa isang 4K base color texture, itakda ang "hd_texture": true (suportado lamang sa meshy-6/latest; ang PBR maps ay nananatili sa 2K). Maaari mo ring gabayan ang istilo ng texture gamit ang isang texture_prompt o isang texture_image_url.

Maaari ba akong bumuo ng isang 3D model na handa para sa 3D printing (STL)?

Oo—ang STL ay nabuo bilang default, kaya ang isang image to 3D STL conversion ay hindi nangangailangan ng karagdagang parameter: kunin lamang ang model_urls.stl kapag natapos na ang gawain. Ginagawa nitong simple ang image to 3D print workflows, dahil ang STL ay ang karaniwang format na inaasahan ng mga slicer. Kung STL lang ang gusto mo, itakda ang "target_formats": ["stl"] upang laktawan ang iba pang mga format at bawasan ang oras ng pagbuo.

Aling mga plano ang may kasamang API access?

Ang API access ay available sa Pro, Studio, at Enterprise na mga plano—ito ay isang Pro-and-above na feature. Ang libreng Starter plan ay hindi kasama ang API access. Tingnan ang Pricing para sa mga detalye.

Gaano katagal valid ang mga download link?

Ang mga download link ay valid sa loob ng 3 araw sa Pro at Studio na mga plano. Ang mga Enterprise customer ay nakakakuha ng permanenteng link. I-save ang iyong mga file kaagad—ang mga expired na link ay hindi na mababawi, at kakailanganin mong patakbuhin muli ang gawain.

Maaari ba akong magpatakbo ng maraming gawain nang sabay-sabay?

Oo, ang mga concurrent request ay sinusuportahan. Kung makatanggap ka ng 429 Too Many Requests error, naabot na ng iyong account ang rate limit nito—ipatupad ang exponential backoff at subukan muli. Tingnan ang pahina ng Rate Limits para sa mga limitasyon ng iyong plano.

Ang gawain ay nagpapakita ng FAILED — ano ang gagawin ko?

Suriin ang task_error.message para sa dahilan. Mga karaniwan:

Kung magpapatuloy ang isyu, makipag-ugnayan sa Meshy support.