릴리프 API

사진 한 장을 부조 형태의 3D 모델과 16비트 깊이 맵으로 변환하여 3D 프린팅, 레이저 각인, CNC 조각에 활용할 수 있습니다.

POST/openapi/v1/relief

릴리프 작업 생성

릴리프 작업을 생성합니다. 이 작업은 사진을 저부조(bas-relief) 모델로 변환합니다. 작업이 성공하면 GLB 파일과 STL 파일 형태의 모델, 16비트 그레이스케일 depth map, 그리고 미리보기 이미지가 생성됩니다. depth map만 받으려면 should_generate_model을 false로 설정하세요.

이 작업은 백그라운드에서 실행됩니다.

릴리프 작업은 리메시, 변환, Auto Split 등 다른 엔드포인트의 입력으로 사용할 수 없습니다. 그런 요청은 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"
}

파라미터

Name
image_url
Type
string
필수
Description
릴리프로 변환할 사진으로, 공개 URL 또는 data URI(data:image/png;base64,...) 형식입니다.
이미지는 최대 20MB, 최소 32 × 32픽셀의 JPG, JPEG, PNG, 또는 WebP 파일이어야 합니다. 긴 쪽은 짧은 쪽의 최대 약 16배까지 가능합니다. 그 외의 이미지는 400을 반환합니다. Meshy는 릴리프를 만들기 전에 투명한 영역을 검은색으로 채웁니다.
Name
variant
Type
string
기본값 low
Description
릴리프 스타일입니다. depth map의 형태를 결정하고 기본 carving_depth_mm을 설정합니다.
사용 가능한 값:
- high: 더 깊게 조각하며, 3D 프린팅 출력물에 적합합니다.
- low: 얕게 조각하며, 레이저 각인, CNC 조각, 얇은 명판에 적합합니다.
null 또는 ""을 전송하는 것은 생략하는 것과 동일합니다. 그 외의 값은 400을 반환합니다.
Name
should_generate_model
Type
boolean
기본값 true
Description
릴리프 모델을 생성할지 여부입니다. depth map만 생성하는 작업으로 설정하려면 false로 지정하세요. 이 경우 모델과 미리보기 이미지는 생성되지 않습니다. Meshy는 여전히 크기, 조각, 베이스, 휨, 해상도 파라미터를 검증하지만 실제로 사용하지는 않습니다. 크레딧 비용도 변경되지 않습니다.

Name
size_mm
Type
number
기본값 60
Description
모델에서 사진의 긴 쪽 길이로, 휘기 전 평평한 상태를 기준으로 20에서 250밀리미터 사이입니다. remove_base를 사용하면 모델이 더 작아질 수 있습니다.
Name
carving_mode
Type
string
기본값 emboss
Description
피사체가 판에서 돌출되는지, 아니면 깎여 들어가는지를 설정합니다.
사용 가능한 값:
- emboss: 사진에서 더 가까운 부분이 돌출됩니다.
- engrave: 깊이가 반전되어, 더 가까운 부분이 깎여 들어갑니다.
depth map은 두 모드에서 동일합니다.
Name
carving_depth_mm
Type
number
기본값 6 (high), 3 (low)
Description
릴리프가 얼마나 깊게 조각되는지를 나타내며, 0에서 60밀리미터 사이입니다. remove_base가 true로 설정된 경우 0은 빈 모델을 남깁니다. 이 경우에도 작업은 성공하며 20크레딧이 청구되고, GLB 및 STL 파일에는 지오메트리가 없습니다.

Name
remove_base
Type
boolean
기본값 false
Description
배경을 잘라내고 베이스 판을 생성하지 않을지 여부입니다. true인 경우 removal_threshold가 배경으로 간주할 기준을 설정합니다. Meshy는 이 값과 관계없이 removal_threshold를 검증합니다.

다음 경우에만 적용 remove_base = true

Name
removal_threshold
Type
number
기본값 0.01
Description
Meshy가 배경을 잘라내는 기준이 되는 깊이로, depth map이 0에서 1 사이일 때 0.01에서 1 사이의 값입니다. 값이 높으면 릴리프 전체가 잘려나가 빈 모델이 남을 수 있으며, 이 경우에도 작업은 성공하며 비용이 청구됩니다.

Name
base_thickness_mm
Type
number
기본값 1, or 0 with remove_base
Description
베이스 판의 두께로, 0.1에서 10밀리미터 사이입니다. remove_base가 true인 경우 생략하거나 0을 전송하세요.

Name
bend_mode
Type
string
기본값 off
Description
릴리프를 휠지, 어느 방향으로 휠지를 설정합니다. off가 아닌 경우 bend_axis와 bend_angle이 휨의 형태를 결정합니다. Meshy는 이 값과 관계없이 이 두 파라미터를 검증합니다.
사용 가능한 값:
- off: 평평한 릴리프입니다.
- convex: 앞면이 바깥쪽으로 볼록해집니다.
- concave: 앞면이 안쪽으로 오목해집니다.

다음 경우에만 적용 bend_mode = convex or concave

Name
bend_axis
Type
string
기본값 xz
Description
휨이 어느 모서리를 따라 말리는지를 설정합니다.
사용 가능한 값:
- xz: 좌우 모서리입니다.
- yz: 위아래 모서리입니다.
Name
bend_angle
Type
number
기본값 60
Description
휨이 이루는 호의 각도로, 0에서 360도 사이입니다. 1보다 작으면 릴리프는 평평하게 유지됩니다.

Name
mesh_resolution
Type
integer
기본값 1024
Description
사진의 긴 쪽을 따라 배치되는 메시 포인트 수로, 512에서 2048 사이입니다. 값이 높을수록 더 세밀한 디테일이 유지되지만 파일 크기가 커집니다. 기본값인 1024에서는 GLB 파일이 약 40~~50MB, STL 파일이 약 80~~105MB입니다. 정사각형 사진은 더 큰 크기를 만듭니다. 2048에서는 각각 약 150MB와 300MB입니다. 휨을 적용하면 파일이 더 커지며, STL 파일은 2048에서 약 800MB에 이를 수 있습니다.

반환값

202 Accepted가 반환되며, result에 새로운 릴리프 작업의 ID가 포함됩니다.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 오류 메시지에 발견된 문제가 표시됩니다. 예를 들면:
- 파라미터 누락: image_url이 전송되지 않았습니다.
- 잘못된 파라미터: 파라미터의 타입이 올바르지 않거나, 범위를 벗어나거나, 사용 가능한 값 중 하나가 아닙니다. 예를 들어 variant가 high나 low가 아니거나, mesh_resolution이 512에서 2048 사이의 정수가 아닌 경우입니다.
- 베이스 두께: remove_base가 true일 때 base_thickness_mm이 0이 아니거나, remove_base가 없을 때 0.1 미만인 경우입니다.
- 접근할 수 없는 URL: Meshy가 image_url 이미지를 다운로드할 수 없는 경우로, 예를 들어 URL이 404를 반환하거나 시간 초과가 발생한 경우입니다.
- 잘못된 이미지: 이미지가 JPG, JPEG, PNG, 또는 WebP 파일이 아니거나, 20MB를 초과하거나, 32 × 32픽셀보다 작거나, 픽셀 수가 너무 많거나, 읽을 수 없는 경우입니다.
- 극단적인 가로세로 비율: 이미지의 긴 쪽이 짧은 쪽의 약 16배를 초과하는 경우입니다.
요청을 수정한 후 다시 전송하세요. Meshy는 이에 대해 비용을 청구하지 않습니다. 오류를 참고하세요.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
예를 들면:
- 크레딧 부족: 계정에 이 작업을 수행할 만큼 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. 크레딧 잔액을 확인한 후 다시 시도하세요.
- 무료 플랜: 작업을 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 후 다시 시도하세요.
Name
403 - Forbidden
Description
콘텐츠 moderation에 의해 이미지가 차단되었습니다. Meshy는 이 요청에 대해 비용을 청구하지 않습니다. 다른 이미지를 전송하세요.
Name
429 - Too Many Requests
Description
다음 한도 중 하나에 도달했습니다:
- 요청을 너무 많이 보냈습니다. 잠시 기다린 후 다시 시도하세요. 속도 제한을 참고하세요.
- 대기 중이거나 실행 중인 작업이 너무 많습니다. 일부가 완료될 때까지 기다린 후 다시 시도하세요.
- 무제한 플랜에서 크레딧이 남아 있지 않은 상태로, 크레딧 없이 실행할 수 있는 작업 수에 도달했습니다. 작업이 완료되기를 기다리거나 크레딧을 추가하세요.

작업 실행 중 안전성 검사에서 이미지가 거부되면, 작업은 task_error.type이 invalid_input으로, task_error.code가 provider_content_refused로 설정된 채 실패합니다. Meshy는 해당 작업의 크레딧을 환불합니다. 다른 이미지를 전송하세요. 오류를 참고하세요.

GET/openapi/v1/relief/:id

Relief 작업 가져오기

ID로 Relief 작업을 반환합니다.

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
}

매개변수

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

반환 값

Relief 작업 객체를 반환합니다.

DELETE/openapi/v1/relief/:id

릴리프 작업 삭제

릴리프 작업을 모델, 깊이 맵, 데이터를 포함하여 영구적으로 삭제합니다. 삭제는 취소할 수 없습니다.

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."
}

경로 매개변수

Name
id
Type
path
Description
삭제할 작업의 ID입니다.

작업 상태

PENDING 상태인 작업을 삭제하면 생성 시 사용된 크레딧이 환불됩니다.

IN_PROGRESS 상태인 작업은 삭제할 수 없습니다. 요청은 409 Conflict를 반환하며, 작업은 계속 실행됩니다. Meshy는 이미 시작된 작업에 대해서는 환불하지 않으므로, 이를 삭제하면 크레딧과 결과물 모두를 잃게 됩니다. 작업이 SUCCEEDED 또는 FAILED 상태가 될 때까지 기다린 후 삭제하세요.

SUCCEEDED 상태인 작업을 삭제해도 크레딧은 환불되지 않습니다. FAILED 상태인 작업은 실패했을 때 이미 환불되었습니다.

반환값

작업이 삭제되면 200 OK를 반환하고, 작업이 IN_PROGRESS 상태이면 409 Conflict를 반환합니다.

GET/openapi/v1/relief

List Relief tasks

사용자의 Relief 작업 목록을 반환합니다.

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

Parameters

Name
page_num
Type
integer
Description
반환할 페이지 번호입니다. 1부터 시작하며 기본값은 1입니다.
Name
page_size
Type
integer
Description
페이지당 작업 수이며 최대 100까지 가능합니다. 기본값은 10입니다. Meshy는 101에서 255 사이의 값을 100으로 처리하며, 그보다 큰 값은 400을 반환합니다.
Name
sort_by
Type
string
Description
정렬 순서입니다.
사용 가능한 값:
- +created_at: 오래된 순
- -created_at: 최신 순

Returns

페이지네이션된 Relief 작업 객체 목록입니다.

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

Relief 작업 스트리밍

Relief 작업의 업데이트를 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
}

Parameters

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

Returns

Relief 작업 객체의 스트림을 Server-Sent Events로 반환합니다.

각 message 이벤트는 Relief 작업 조회가 반환하는 것과 동일한 전체 작업 객체를 담고 있습니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안 이벤트 간에 변경되는 필드는 progress, status, started_at, 그리고 preceding_tasks(이 작업보다 앞선 작업이 있을 때만 존재)입니다. model_urls, depth_map_url, thumbnail_url은 작업이 SUCCEEDED 상태에 도달하면 값이 채워집니다. depth map만 요청한 작업의 경우 model_urls는 {}로 유지되고 thumbnail_url은 빈 값으로 유지됩니다.

error 이벤트에는 status_code와 message만 포함되므로, status를 읽기 전에 이벤트 이름을 먼저 확인하세요.

릴리프 작업 객체

릴리프 작업 객체는 사진으로 만든 하나의 릴리프를 설명합니다. model_urls, depth_map_url, thumbnail_url은 항상 존재하며, 작업이 성공하기 전까지는 비어 있습니다.

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
작업 ID입니다. 불투명한 문자열로 취급하고, 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형이며, 항상 relief입니다.
Name
model_urls
Type
object
Description
릴리프 모델의 다운로드 URL입니다. 파일 크기가 클 수 있으며, 일반적인 크기는 mesh_resolution에 나와 있습니다.
- Name
  glb
  Type
  string
  Description
  텍스처가 없는 GLB 파일입니다. 단위는 미터입니다. depth map 전용 작업에서는 존재하지 않습니다.
- Name
  stl
  Type
  string
  Description
  동일한 모델을 바이너리 STL 파일로 제공합니다. 단위는 밀리미터이므로, Z축을 위로 하여 릴리프의 실제 크기로 열립니다. depth map 전용 작업에서는 존재하지 않습니다.
Name
depth_map_url
Type
string
Description
릴리프가 만들어진 16비트 그레이스케일 depth map의 다운로드 URL입니다. 밝은 픽셀일수록 더 높습니다. 값은 밀리미터가 아닌 상대적인 높이입니다. 레이저 조각 및 CNC 소프트웨어에서 높이 맵으로 사용할 수 있습니다. 파일 크기는 약 1~2MB입니다. 없을 경우 비어 있습니다.
Name
thumbnail_url
Type
string
Description
릴리프 모델의 미리보기 이미지 다운로드 URL입니다. depth map 전용 작업을 포함하여 렌더링된 이미지가 없으면 비어 있습니다.
Name
progress
Type
integer
Description
작업이 완료된 정도를 백분율로 나타냅니다. 작업이 시작되기 전까지는 0이고, 성공하면 100입니다.
Name
status
Type
string
Description
작업 상태이며, PENDING, IN_PROGRESS, SUCCEEDED, FAILED 중 하나입니다.
Name
preceding_tasks
Type
integer
Description
대기열에서 이 작업보다 앞에 있는 작업의 수입니다. 값이 0일 때는 필드가 생략되므로, 앞선 작업이 있는 동안에만 표시됩니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시간으로, Unix 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시간으로, Unix 밀리초 단위입니다. 작업이 시작되기 전까지는 0입니다.
Name
finished_at
Type
timestamp
Description
작업이 종료된 시간으로, Unix 밀리초 단위입니다. 작업이 종료되기 전까지는 0입니다.
Name
expires_at
Type
timestamp
Description
작업 결과가 만료되는 시간으로, Unix 밀리초 단위입니다. 작업이 종료되기 전까지는 0입니다.
Name
task_error
Type
object
Description
작업이 실패했을 때의 오류 상세 정보입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
작업에서 사용된 크레딧 수입니다: 20이며, FAILED 작업의 경우 0이고 Meshy가 환불합니다.