Relyebo API

I-convert ang isang larawan sa isang bas-relief na 3D model at isang 16-bit na depth map, para sa 3D printing, laser engraving, at CNC carving.

POST/openapi/v1/relief

Gumawa ng Relief task

Gumagawa ng Relief task. Ginagawang bas-relief model ng task na ito ang isang larawan. Kapag matagumpay ito, ang task ay gumagawa ng model bilang GLB file at STL file, isang 16-bit grayscale depth map, at isang preview image. Para makuha lamang ang depth map, itakda ang should_generate_model sa false.

Tumatakbo ang task sa background.

Hindi pwedeng maging input ng ibang endpoint ang Relief task, tulad ng Remesh, I-convert, o Auto Split. Ang mga request na iyon ay nagbabalik ng 403.

Request

POST

/openapi/v1/relief

# Simple request: a low relief, 60 mm on its longer side
curl https://api.meshy.ai/openapi/v1/relief \
-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>"
  }'

# Advanced request: a deep 120 mm relief with a thicker base, curved from side to side
curl https://api.meshy.ai/openapi/v1/relief \
-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>",
    "variant": "high",
    "size_mm": 120,
    "carving_depth_mm": 10,
    "base_thickness_mm": 3,
    "bend_mode": "convex",
    "bend_angle": 90
  }'

Response

{
  "result": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20"
}

Mga Parameter

Name
image_url
Type
string
Kinakailangan
Description
Ang larawan na gagawing relief, bilang isang public URL o data URI (data:image/png;base64,...).
Dapat ang larawan ay isang JPG, JPEG, PNG, o WebP file na hindi hihigit sa 20 MB, at hindi bababa sa 32 × 32 pixels. Ang mas mahabang gilid nito ay pwedeng umabot lamang ng halos 16 beses ng mas maiksing gilid nito. Ang anumang ibang larawan ay nagbabalik ng 400. Pinupuno ni Meshy ng itim ang mga transparent na bahagi bago buuin ang relief.
Name
variant
Type
string
default low
Description
Ang istilo ng relief. Hinuhubog nito ang depth map at itinatakda ang default na carving_depth_mm.
Mga available na value:
- high: mas malalim na ukit, para sa mga piyesang 3D-printed.
- low: mababaw na ukit, para sa laser engraving, CNC carving, at manipis na plaques.
Ang pagpapadala ng null o "" ay katumbas ng hindi na pagsasama nito. Ang anumang ibang value ay nagbabalik ng 400.
Name
should_generate_model
Type
boolean
default true
Description
Kung bubuuin ang relief model. Itakda ito sa false para sa isang depth-map-only task, na walang model at walang preview image. Sinusuri pa rin ni Meshy ang mga parameter ng size, carving, base, bend, at resolution, ngunit hindi ginagamit ang mga ito. Hindi nito binabago ang halaga ng credit.

Name
size_mm
Type
number
default 60
Description
Ang haba ng mas mahabang gilid ng larawan sa model, sinusukat habang patag bago ang anumang bend, mula 20 hanggang 250 millimeters. Gamit ang remove_base, pwedeng maging mas maliit ang model.
Name
carving_mode
Type
string
default emboss
Description
Kung ang subject ay nakausli mula sa plate o inukit papunta rito.
Mga available na value:
- emboss: ang mga bahaging mas malapit ng larawan ay nakausli.
- engrave: ang lalim ay baligtad, kaya ang mga bahaging mas malapit ay inuukit papasok.
Pareho ang depth map sa parehong mode.
Name
carving_depth_mm
Type
number
default 6 (high), 3 (low)
Description
Kung gaano kalalim ang pag-ukit ng relief, mula 0 hanggang 60 millimeters. Kapag ang remove_base ay itinakda sa true, ang 0 ay nag-iiwan ng walang laman na model. Matagumpay pa rin ang task at nagkakahalaga ng 20 credits, at walang heometriya ang GLB at STL files nito.

Name
remove_base
Type
boolean
default false
Description
Kung puputulin ang background at hindi na bubuo ng base plate. Kapag ito ay true, itinatakda ng removal_threshold kung ano ang itinuturing na background. Sinusuri ni Meshy ang removal_threshold sa anumang pagkakataon.

Naaangkop lamang kapag remove_base = true

Name
removal_threshold
Type
number
default 0.01
Description
Ang lalim na pinagbabatayan ng pagputol ni Meshy sa background, mula 0.01 hanggang 1, kung saan ang depth map ay tumatakbo mula 0 hanggang 1. Ang isang mataas na value ay pwedeng maputol ang buong relief at mag-iwan ng walang laman na model, na matagumpay pa rin at sisingilin.

Name
base_thickness_mm
Type
number
default 1, or 0 with remove_base
Description
Ang kapal ng base plate, mula 0.1 hanggang 10 millimeters. Kapag ang remove_base ay true, iwan itong hindi kasama o ipadala ang 0.

Name
bend_mode
Type
string
default off
Description
Kung bebendan ang relief, at sa anong direksyon. Kapag hindi ito off, hinuhubog ng bend_axis at bend_angle ang bend. Sinusuri ni Meshy ang mga ito sa anumang pagkakataon.
Mga available na value:
- off: isang patag na relief.
- convex: ang harapan ay namumukol palabas.
- concave: ang harapan ay kumukurba papasok.

Naaangkop lamang kapag bend_mode = convex or concave

Name
bend_axis
Type
string
default xz
Description
Aling mga gilid ang pinipiliit ng bend.
Mga available na value:
- xz: ang kaliwa at kanang gilid.
- yz: ang itaas at ibabang gilid.
Name
bend_angle
Type
number
default 60
Description
Ang arko na sinasaklaw ng bend, mula 0 hanggang 360 degrees. Sa ibaba ng 1, nananatiling patag ang relief.

Name
mesh_resolution
Type
integer
default 1024
Description
Ang bilang ng mga mesh point sa kahabaan ng mas mahabang gilid ng larawan, mula 512 hanggang 2048. Ang mas mataas na value ay pinapanatili ang mas pinong detalye at gumagawa ng mas malalaking file. Sa default na 1024, ang GLB file ay humigit-kumulang 40 hanggang 50 MB at ang STL file ay humigit-kumulang 80 hanggang 105 MB. Ang isang parisukat na larawan ay nagbibigay ng mas malalaking sizes. Sa 2048, humigit-kumulang 150 MB at 300 MB ang mga ito. Pinapalaki ng bend ang mga ito: ang STL file ay pwedeng umabot ng humigit-kumulang 800 MB sa 2048.

Mga Ibinabalik

202 Accepted, kasama ang ID ng bagong Relief task sa result.

Mga Paraan ng Pagkabigo

Name
400 - Bad Request
Description
Hindi matatakbo ang request. Sinasabi ng error message kung aling problema ang natagpuan nito. Halimbawa:
- Kulang na parameter: hindi naipadala ang image_url.
- Hindi wastong parameter: Mali ang type ng isang parameter, wala sa saklaw nito, o hindi isa sa mga available na value nito. Halimbawa, ang variant ay hindi high o low, o ang mesh_resolution ay hindi isang integer mula 512 hanggang 2048.
- Kapal ng base: ang base_thickness_mm ay hindi 0 kapag ang remove_base ay itinakda sa true, o mas mababa sa 0.1 kapag wala ito.
- Hindi maabot na URL: hindi ma-download ni Meshy ang larawan sa image_url, halimbawa dahil ang URL ay nagbabalik ng 404 o nag-time out.
- Hindi wastong larawan: ang larawan ay hindi isang JPG, JPEG, PNG, o WebP file, ay mahigit sa 20 MB, ay mas maliit sa 32 × 32 pixels, mayroong napakaraming pixels, o hindi mabasa.
- Matinding aspect ratio: ang mas mahabang gilid ng larawan ay mahigit sa halos 16 beses ng mas maiksing gilid nito.
Ayusin ang request, pagkatapos ay ipadala muli ito. Hindi sinisingil ito ni Meshy. Tingnan ang Errors.
Name
401 - Unauthorized
Description
Nawawala o hindi wasto ang API key. Suriin ang Authorization header.
Name
402 - Payment Required
Description
Halimbawa:
- Kulang na credits: Walang sapat na credits ang account para sa task na ito, o naabot ng account ang isang credit limit. Suriin ang iyong balanse ng credit, pagkatapos ay subukan muli.
- Free plan: Nangangailangan ng bayad na plan ang paggawa ng task. I-upgrade ang iyong plan sa iyong mga setting ng subscription, pagkatapos ay subukan muli.
Name
403 - Forbidden
Description
Hinarangan ng content moderation ang larawan. Hindi sinisingil ni Meshy ang request. Magpadala ng ibang larawan.
Name
429 - Too Many Requests
Description
Isa sa mga limitasyong ito ang naabot:
- Nagpadala ka ng napakaraming request. Maghintay, pagkatapos ay subukan muli. Tingnan ang Rate limits.
- Masyadong maraming task mo ang nasa queue o tumatakbo. Maghintay na matapos ang ilan, pagkatapos ay subukan muli.
- Sa isang unlimited plan na walang natitirang credits, naabot mo ang bilang ng mga task na pwedeng tumakbo nang walang credits. Maghintay na matapos ang isang task, o magdagdag ng credits.

Kung tinanggihan ng safety check ang larawan habang tumatakbo ang task, mabibigo ang task na ang task_error.type ay itinakda sa invalid_input at ang task_error.code ay itinakda sa provider_content_refused. Ibabalik ni Meshy ang credits ng task. Magpadala ng ibang larawan. Tingnan ang Errors.

GET/openapi/v1/relief/:id

Kumuha ng Relyebo task

Nagbabalik ng isang Relyebo task gamit ang kanyang ID.

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Mga Parameter

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

Ibinabalik

Ang Relief task object.

DELETE/openapi/v1/relief/:id

Mag-delete ng Relief task

Permanenteng binubura nito ang isang Relief task, kasama ang modelo, depth map, at data nito. Hindi na ito mababawi kapag na-delete na.

Request

DELETE

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
  -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 i-delete.

Katayuan ng task

Ang pag-delete sa isang PENDING na task ay nagre-refund ng mga credits na nagamit noong ginawa mo ito.

Hindi maaaring i-delete ang isang IN_PROGRESS na task. Ibabalik ng request ang 409 Conflict, at magpapatuloy pa ring tumatakbo ang task. Hindi nagre-refund si Meshy para sa isang task na nasimulan na, kaya ang pag-delete dito ay magiging kalugihan mo pareho ang credits at ang resulta. Hintayin munang umabot ito sa SUCCEEDED o FAILED, bago ito i-delete.

Ang pag-delete sa isang SUCCEEDED na task ay hindi nagre-refund ng credits nito. Ang isang FAILED na task ay na-refund na noong nabigo ito.

Mga ibinabalik na halaga

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

GET/openapi/v1/relief

List Relief tasks

Nagbabalik ng listahan ng iyong mga Relyebo task.

Request

GET

/openapi/v1/relief

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

Response

[
  {
    "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
    "type": "relief",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
    },
    "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000060000,
    "expires_at": 1700259260000,
    "task_error": null,
    "consumed_credits": 20
  }
]

Mga Parameter

Name
page_num
Type
integer
Description
Ang numero ng pahinang ibabalik. Nagsisimula sa at ang default ay 1.
Name
page_size
Type
integer
Description
Ang bilang ng mga task kada pahina, hanggang 100. Ang default ay 10. Itinuturing ng Meshy ang halagang mula 101 hanggang 255 bilang 100, at ang mas malaking halaga ay magbabalik ng 400.
Name
sort_by
Type
string
Description
Ang pagkakasunod-sunod ng pag-uuri.
Mga magagamit na halaga:
- +created_at: pinakaluma muna
- -created_at: pinakabago muna

Ibinabalik

Isang pinaginang listahan ng mga Relyebo task object.

GET/openapi/v1/relief/:id/stream

Mag-stream ng Relief task

Nagsa-stream ng mga update ng isang Relief task bilang Server-Sent Events (SSE).

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/stream

curl -N https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Mga Parameter

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

Ibinabalik

Isang stream ng Relief task objects bilang Server-Sent Events.

Bawat message event ay may hawak na kumpletong task object, kapareho ng ibinabalik ng Get a Relief task. Habang ang task ay PENDING o IN_PROGRESS, ang mga field na nagbabago sa pagitan ng mga event ay progress, status, started_at, at preceding_tasks (naroroon lamang habang may mga task na nauuna dito). Nakukuha ng model_urls, depth_map_url, at thumbnail_url ang kanilang mga value kapag naabot ng task ang SUCCEEDED. Ang isang task na depth-map lamang ay pananatilihin ang model_urls bilang {} at ang thumbnail_url na walang laman.

Ang isang error event ay may hawak lamang ng status_code at message, kaya suriin ang pangalan ng event bago basahin ang status.

The Relyebo task object

Ang isang Relyebo task object ay naglalarawan ng isang relyebo na ginawa mula sa isang larawan. Palaging naroroon ang model_urls, depth_map_url, at thumbnail_url, at walang laman hanggang magtagumpay ang task.

The Relief Task Object

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Depth map only

{
  "id": "0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31",
  "type": "relief",
  "model_urls": {},
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31/output/depth.png?Expires=***",
  "thumbnail_url": "",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1700259230000,
  "task_error": null,
  "consumed_credits": 20
}

Name
id
Type
string
Description
Ang ID ng task. Ituring itong isang opaque na string, at huwag umasa sa format nito.
Name
type
Type
string
Description
Ang uri ng task, palaging relief.
Name
model_urls
Type
object
Description
Mga download URL para sa relyebo model. Maaaring malaki ang mga file; nakalista sa mesh_resolution ang mga karaniwang laki.
- Name
  glb
  Type
  string
  Description
  Ang GLB file, walang texture. Ang mga unit nito ay metro. Wala kung depth-map-only ang task.
- Name
  stl
  Type
  string
  Description
  Ang parehong model bilang isang binary STL file. Ang mga unit nito ay milimetro, kaya nabubuksan ito sa tunay na laki ng relyebo, na ang Z ay nakaturo pataas. Wala kung depth-map-only ang task.
Name
depth_map_url
Type
string
Description
Download URL para sa 16-bit grayscale depth map kung saan ginawa ang relyebo. Mas maliwanag na pixel ay mas mataas. Ang mga value ay kamag-anak na taas, hindi milimetro. Magagamit ito ng software para sa laser engraving at CNC bilang isang height map. Ang file ay humigit-kumulang 1 hanggang 2 MB. Walang laman kung wala nito.
Name
thumbnail_url
Type
string
Description
Download URL para sa preview image ng relyebo model. Walang laman kung walang na-render, kabilang na ang depth-map-only na task.
Name
progress
Type
integer
Description
Kung gaano karami ang natapos na sa task, bilang isang porsyento. 0 ito hanggang magsimula ang task at 100 kapag nagtagumpay ito.
Name
status
Type
string
Description
Ang status ng task, isa sa PENDING, IN_PROGRESS, SUCCEEDED, o FAILED.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga task na nauuna sa pila kaysa dito. Hindi isinasama ang field na ito kapag ang value ay 0, kaya lumalabas lamang ito habang may mga task na nauuna dito.
Name
created_at
Type
timestamp
Description
Oras nang ginawa ang task, sa Unix milliseconds.
Name
started_at
Type
timestamp
Description
Oras nang nagsimula ang task, sa Unix milliseconds. 0 ito hanggang magsimula ang task.
Name
finished_at
Type
timestamp
Description
Oras nang natapos ang task, sa Unix milliseconds. 0 ito hanggang matapos ang task.
Name
expires_at
Type
timestamp
Description
Oras nang mag-e-expire ang resulta ng task, sa Unix milliseconds. 0 ito hanggang matapos ang task.
Name
task_error
Type
object
Description
Ang detalye ng error kapag nabigo ang task. Tingnan ang Errors.
Name
consumed_credits
Type
integer
Description
Ang bilang ng mga credits na ginamit ng task: 20, o 0 para sa isang FAILED na task, na ire-refund ng Meshy.