Quickstart

Ito ang API reference para sa programmatic na pakikipag-ugnayan sa Meshy.

Gumagamit ng AI coding assistant? Tingnan ang aming pahina ng AI Integration — i-install ang Meshy MCP server para sa tool-calling access mula sa Claude Code, Cursor, Windsurf, at iba pang MCP-compatible na mga tool, o ituro ang isang plain chat agent sa llms.txt.

Nagbibigay ang Meshy API ng simpleng interface para bumuo ng mga 3D model at texture mula sa mga text prompt at image. Sundan ang gabay na ito para mabilis na makapagsimula.

Gumawa ng API key

Gumawa ng API key sa API settings page dito, na gagamitin mo para secure na i-authenticate ang iyong mga request. Ang format ng API key ay msy-<random-string>.

Bumuo ng API key

Kapag nakabuo ka na ng API key, itago ito sa isang secure na lokasyon.

test mode API key

Sa panahon ng development at testing, maaari mong gamitin ang aming test mode API key para tuklasin ang API nang hindi kinokonsumo ang iyong credits:

msy_dummy_api_key_for_test_mode_12345678

May mga sumusunod na katangian ang espesyal na API key na ito:

Maaari itong gamitin para gumawa ng mga request sa lahat ng Meshy API endpoints
Walang credits na nakokonsumo kapag ginagamit ang key na ito
Lahat ng valid na request ay magbabalik ng parehong sample task results, anuman ang mga input parameter
Ang data structure ng response ay eksaktong tutugma sa production API
Perpekto para sa pag-test ng iyong API integration bago lumipat sa iyong tunay na API key

Ang test mode API key ay para lamang sa development purposes. Para sa production use, pakigamit ang sarili mong API key.

Gawin ang Iyong Unang "Text to 3D" API Request

Sa halimbawang ito, bubuo tayo ng 3D model mula sa isang text prompt gamit ang text-to-3d endpoint. May dalawang stage ang proseso: ang preview stage at ang refine stage. Sa preview stage, binubuo ang isang base mesh na walang inilapat na texture, kaya maaari mong suriin ang heometriya. Sa refine stage, nilalagyan ng texture ang preview mesh batay sa text prompt.

Ipapakita namin sa iyo kung paano gawin ang mga request na ito sa isang Python script.

Preview

Nagbibigay ang Meshy ng isang set ng REST API endpoints. Maaari mong gamitin ang mga ito gamit ang anumang HTTP client na gusto mo. Anuman ang API na tatawagin mo, ang API key ay palaging ipinapasa bilang header na pinangalanang Authorization. Pakitandaang i-export ang iyong API key bilang environment variable na pinangalanang MESHY_API_KEY bago gamitin ang script na ito.

Ang mahahalagang parameter para sa preview request ay mode, na palaging "preview", at prompt, isang paglalarawan ng model na kailangan mo. Sa halimbawang ito, tinukoy din namin ang should_remesh, ngunit opsyonal ito.

api_request.py

import requests
import os
import time

headers = {
  "Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}

# 1. Generate a preview model and get the task ID

generate_preview_request = {
  "mode": "preview",
  "prompt": "a monster mask",
  "should_remesh": True,
}

generate_preview_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_preview_request,
)

generate_preview_response.raise_for_status()

preview_task_id = generate_preview_response.json()["result"]

print("Preview task created. Task ID:", preview_task_id)

Nakukumpleto nito ang preview API call.

Pakitandaan na ang Meshy API ay gumagamit ng asynchronous execution model, ibig sabihin kapag gumawa ka ng task, ang API endpoint ay nagbabalik lamang ng task ID. Pagkatapos, kailangan mong i-poll ang task status endpoint gamit ang ID na ito para tingnan kung tapos na ang task.

api_request.py

# 2. Poll the preview task status until it's finished

preview_task = None

while True:
  preview_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
    headers=headers,
  )

  preview_task_response.raise_for_status()

  preview_task = preview_task_response.json()

  if preview_task["status"] == "SUCCEEDED":
    print("Preview task finished.")
    break

  print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

Kapag tapos na ang task, maa-access mo ang mga model URL mula sa response nito. I-download natin ang model mula sa field na model_urls sa response.

api_request.py

# 3. Download the preview model in glb format

preview_model_url = preview_task["model_urls"]["glb"]

preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()

with open("preview_model.glb", "wb") as f:
  f.write(preview_model_response.content)

print("Preview model downloaded.")

Kung maayos ang lahat hanggang dito, ang iyong preview_model.glb ay dapat magmukhang katulad nito. Hindi ito magiging eksaktong tugma, dahil sa intrinsic randomness sa AI pipeline.

Preview na model

Refine

Magpatuloy tayo sa refine stage. Para simulan ang refine request, ibigay ang preview task ID bilang isang input parameter.

api_request.py

# 4. Generate a refined model and get the task ID

generate_refined_request = {
  "mode": "refine",
  "preview_task_id": preview_task_id,
}

generate_refined_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_refined_request,
)

generate_refined_response.raise_for_status()

refined_task_id = generate_refined_response.json()["result"]

print("Refined task created. Task ID:", refined_task_id)

# 5. Poll the refined task status until it's finished

refined_task = None

while True:
  refined_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
    headers=headers,
  )

  refined_task_response.raise_for_status()

  refined_task = refined_task_response.json()

  if refined_task["status"] == "SUCCEEDED":
    print("Refined task finished.")
    break

  print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 6. Download the refined model in glb format

refined_model_url = refined_task["model_urls"]["glb"]

refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()

with open("refined_model.glb", "wb") as f:
  f.write(refined_model_response.content)

print("Refined model downloaded.")

Ang 3D model na refined_model.glb ay ganap nang nalagyan ng texture ✨.

Refined na model

Pagsama-samahin Ito

Narito ang kumpletong code para sa paggamit ng Text to 3D API.

api_request.py

import requests
import os
import time

headers = {
  "Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}

# 1. Generate a preview model and get the task ID

generate_preview_request = {
  "mode": "preview",
  "prompt": "a monster mask",
  "should_remesh": True,
}

generate_preview_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_preview_request,
)

generate_preview_response.raise_for_status()

preview_task_id = generate_preview_response.json()["result"]

print("Preview task created. Task ID:", preview_task_id)

# 2. Poll the preview task status until it's finished

preview_task = None

while True:
  preview_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
    headers=headers,
  )

  preview_task_response.raise_for_status()

  preview_task = preview_task_response.json()

  if preview_task["status"] == "SUCCEEDED":
    print("Preview task finished.")
    break

  print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 3. Download the preview model in glb format

preview_model_url = preview_task["model_urls"]["glb"]

preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()

with open("preview_model.glb", "wb") as f:
  f.write(preview_model_response.content)

print("Preview model downloaded.")

# 4. Generate a refined model and get the task ID

generate_refined_request = {
  "mode": "refine",
  "preview_task_id": preview_task_id,
}

generate_refined_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_refined_request,
)

generate_refined_response.raise_for_status()

refined_task_id = generate_refined_response.json()["result"]

print("Refined task created. Task ID:", refined_task_id)

# 5. Poll the refined task status until it's finished

refined_task = None

while True:
  refined_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
    headers=headers,
  )

  refined_task_response.raise_for_status()

  refined_task = refined_task_response.json()

  if refined_task["status"] == "SUCCEEDED":
    print("Refined task finished.")
    break

  print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 6. Download the refined model in glb format

refined_model_url = refined_task["model_urls"]["glb"]

refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()

with open("refined_model.glb", "wb") as f:
  f.write(refined_model_response.content)

print("Refined model downloaded.")

Kopyahin at i-paste ang code sa isang Python script at patakbuhin ito.

Run the script

python api_request.py

Dapat kang makakita ng output sa iyong terminal na katulad ng sumusunod:

Patakbuhin ang script

Mga Susunod na Hakbang

Mas gusto mo bang subukan muna ang endpoints nang hindi nagsusulat ng code? Gamitin ang API Playground para i-configure at patakbuhin ang isang request, pagkatapos ay kopyahin ang nabuong snippet.
Makikita mo ang kumpletong API reference sa seksyong "API Endpoints", na nagbibigay ng detalyadong impormasyon tungkol sa bawat API.
Tuklasin ang mga detalye tungkol sa Pricing, Rate Limits, at kung paano mag-troubleshoot ng common Errors.
Huwag kalimutang regular na tingnan ang aming changelog para sa mga update at bug fix.
May feedback o may kinahaharap na issue? Sumali sa aming Discord komunidad - gusto naming marinig ang mula sa iyo!