리메시 API

리메시 API를 사용하면 다른 Meshy API(예: 이미지로 3D 또는 텍스트로 3D)로 생성된 기존 3D 모델을 다양한 형식으로 리메시하고 내보낼 수 있습니다. 이 섹션에서는 리메시 API를 사용하는 방법에 대한 세부 정보를 제공합니다.

POST/openapi/v1/remesh

리메시 작업 생성

이 엔드포인트는 새로운 리메시 작업을 생성합니다.

포맷 변환 및 크기 조정을 위해서는 전용 변환 API 및 크기 조정 API를 사용하세요. 아래의 지원 중단된 파라미터들은 계속 작동하지만, 새로운 통합을 위해서는 새로운 엔드포인트를 권장합니다.

파라미터

input_task_id 또는 model_url 중 하나만 필수입니다. 둘 다 제공된 경우, input_task_id가 우선합니다.

Name
input_task_id
Type
string
필수
Description
리메시하고자 하는 완료된 이미지로 3D 또는 텍스트로 3D 작업의 ID입니다. 이 작업은 다음 작업 중 하나여야 합니다: 텍스트로 3D 미리보기, 텍스트로 3D 정제, 이미지로 3D 또는 리텍스처. 또한, SUCCEEDED 상태여야 합니다.

Name
model_url
Type
string
필수
Description
Meshy가 리메시할 3D 모델을 공개적으로 접근 가능한 URL 또는 데이터 URI를 통해 제공하세요. 지원되는 포맷: .glb, .gltf, .obj, .fbx, .stl.
데이터 URI의 경우, MIME 타입: application/octet-stream을 사용하세요.

Name
target_formats
Type
string[]
기본값 ["glb"]
Description
리메시된 모델의 대상 포맷 목록입니다. 생략된 경우, GLB만 생성됩니다.
사용 가능한 값: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
기본값 triangle
Description
생성된 모델의 topology를 지정하세요.
사용 가능한 값:
- quad: 쿼드 중심의 메시 생성.
- triangle: 디시메이션된 삼각형 메시 생성.
Name
target_polycount
Type
integer
기본값 30,000
Description
생성된 모델의 목표 폴리곤 수를 지정하세요. 실제 폴리곤 수는 지오메트리의 복잡성에 따라 목표와 다를 수 있습니다.
유효한 값 범위는 사용자 등급에 따라 다릅니다:
- 100에서 300,000 (포함)
Name
decimation_mode
Type
integer
Description
폴리곤 수 수준을 설정하여 적응형 디시메이션을 활성화합니다. 설정된 경우, target_polycount는 무시됩니다.
사용 가능한 값:
- 1: 적응형 — 초고 폴리곤 수.
- 2: 적응형 — 고 폴리곤 수.
- 3: 적응형 — 중간 폴리곤 수.
- 4: 적응형 — 저 폴리곤 수.
Name
resize_height
Type
number
⚠ 사용 중단
기본값 0
Description
모델을 미터 단위로 특정 높이로 크기 조정합니다. 전용 크기 조정 API를 사용하는 것을 권장합니다.
auto_size, resize_height, 및 resize_longest_side는 상호 배타적입니다.
Name
resize_longest_side
Type
number
⚠ 사용 중단
기본값 0
Description
모델의 가장 긴 경계 상자 차원이 미터 단위로 지정된 값과 같아지도록 크기 조정합니다. 전용 크기 조정 API를 사용하는 것을 권장합니다.
auto_size, resize_height, 및 resize_longest_side는 상호 배타적입니다.
Name
auto_size
Type
boolean
⚠ 사용 중단
기본값 false
Description
true로 설정된 경우, 서비스는 AI 비전을 사용하여 객체의 실제 높이를 자동으로 추정하고 모델을 이에 맞게 크기 조정합니다. 전용 크기 조정 API를 사용하는 것을 권장합니다.
auto_size, resize_height, 및 resize_longest_side는 상호 배타적입니다.

다음 경우에만 적용 auto_size = true

Name
origin_at
Type
string
⚠ 사용 중단
기본값 bottom
Description
원점의 위치입니다. 전용 크기 조정 API를 사용하는 것을 권장합니다.
사용 가능한 값: bottom, center.

Name
convert_format_only
Type
boolean
⚠ 사용 중단
Description
true로 설정된 경우, 서비스는 입력 모델 파일의 포맷만 변경하며, topology, resize_height, 및 target_polycount와 같은 다른 입력은 무시합니다. 전용 변환 API를 사용하는 것을 권장합니다.
convert_format_only가 true로 설정된 경우, target_formats를 제공해야 합니다.

Name
alpha_thumbnail
Type
boolean
기본값 false
Description
true로 설정된 경우, 작업은 추가로 투명 배경(RGBA) 버전의 미리보기를 렌더링하고, GET 응답에서 alpha_thumbnail_url로 반환합니다. 기존 thumbnail_url 필드는 변경되지 않습니다.

반환값

응답의 result 속성에는 새로 생성된 리메시 작업의 id가 포함되어 있습니다.

실패 모드

Name
400 - Bad Request
Description
요청이 허용되지 않았습니다. 일반적인 원인:
- 파라미터 누락: model_url 또는 input_task_id 중 하나를 제공해야 합니다.
- 잘못된 입력 작업: input_task_id는 지원되는 모델의 성공적인 작업을 참조해야 합니다.
- 잘못된 모델 포맷: model_url이 지원되지 않는 확장자를 가진 파일을 가리킵니다.
- 접근 불가능한 URL: model_url을 다운로드할 수 없습니다.
- 잘못된 topology: topology 파라미터가 잘못되었습니다.
- 상호 배타적 파라미터: auto_size와 resize_height는 동시에 설정할 수 없습니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인하세요.
Name
402 - Payment Required
Description
이 작업을 수행하기 위한 크레딧이 부족합니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

/openapi/v1/remesh

# Basic remesh with custom formats and resize
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

# Quad remesh with auto-size
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "auto_size": true
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/remesh/:id

리메시 작업 검색

이 엔드포인트는 ID로 리메시 작업을 검색합니다.

매개변수

Name
id
Type
path
Description
검색할 리메시 작업의 ID입니다.

반환값

리메시 작업 객체입니다.

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

DELETE/openapi/v1/remesh/:id

리메시 작업 삭제

이 엔드포인트는 리메시 작업과 관련된 모든 모델 및 데이터를 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

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

반환값

성공 시 200 OK를 반환합니다.

Request

DELETE

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/remesh

리메시 작업 목록

이 엔드포인트를 사용하여 리메시 작업 목록을 검색할 수 있습니다.

매개변수

Name
page_num
Type
integer
기본값 1
Description
페이지네이션을 위한 페이지 번호.
Name
page_size
Type
integer
기본값 10
Description
페이지 크기 제한. 최대 허용 항목 수는 50입니다.
Name
sort_by
Type
string
Description
정렬할 필드.
사용 가능한 값:
- +created_at: 생성 시간 기준 오름차순 정렬.
- -created_at: 생성 시간 기준 내림차순 정렬.

반환값

리메시 작업 객체의 페이지네이션된 목록을 반환합니다.

Request

GET

/openapi/v1/remesh

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]

GET/openapi/v1/remesh/:id/stream

리메시 작업 스트리밍

이 엔드포인트는 Server-Sent Events (SSE)를 사용하여 리메시 작업에 대한 실시간 업데이트를 스트리밍합니다.

매개변수

Name
id
Type
path
Description
스트리밍할 리메시 작업의 고유 식별자입니다.

반환값

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

PENDING 또는 IN_PROGRESS 작업의 경우, 응답 스트림은 필요한 progress 및 status 필드만 포함합니다.

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

리메시 작업 객체

리메시 작업 객체는 Meshy가 기존 3D 모델을 다양한 형식으로 리메시하고 내보내는 작업 단위를 나타냅니다. 이 객체는 다음과 같은 속성을 가지고 있습니다:

속성

Name
id
Type
string
Description
작업의 고유 식별자입니다. 작업 ID에 대해 k-sortable UUID를 구현 세부사항으로 사용하지만, ID 형식에 대한 가정을 하지 말아야 합니다.
Name
type
Type
string
Description
리메시 작업의 유형입니다. 값은 remesh입니다.
Name
model_urls
Type
object
Description
Meshy에 의해 생성된 텍스처가 적용된 3D 모델 파일의 다운로드 가능한 URL입니다. 형식이 생성되지 않은 경우 빈 문자열을 반환하는 대신 해당 형식에 대한 속성이 생략됩니다.
- Name
  glb
  Type
  string
  Description
  GLB 파일의 다운로드 가능한 URL입니다.
- Name
  fbx
  Type
  string
  Description
  FBX 파일의 다운로드 가능한 URL입니다.
- Name
  obj
  Type
  string
  Description
  OBJ 파일의 다운로드 가능한 URL입니다.
- Name
  usdz
  Type
  string
  Description
  USDZ 파일의 다운로드 가능한 URL입니다.
- Name
  blend
  Type
  string
  Description
  Blender 파일의 다운로드 가능한 URL입니다.
- Name
  stl
  Type
  string
  Description
  STL 파일의 다운로드 가능한 URL입니다.
- Name
  3mf
  Type
  string
  Description
  3MF 파일의 다운로드 가능한 URL입니다. target_formats를 통해 3mf가 요청된 경우에만 존재합니다.
Name
thumbnail_url
Type
string
Description
리메시된 모델에서 렌더링된 미리보기 이미지의 다운로드 가능한 URL입니다.
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url의 투명 배경(RGBA) 버전의 다운로드 가능한 URL입니다. 작업이 alpha_thumbnail: true로 생성되고 투명 미리보기가 성공적으로 렌더링된 경우에만 존재하며, 그렇지 않으면 이 필드는 생략됩니다.
Name
progress
Type
integer
Description
작업의 진행 상황입니다. 작업이 아직 시작되지 않은 경우 이 속성은 0이 됩니다. 작업이 성공하면 100이 됩니다.
Name
status
Type
string
Description
작업의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED 중 하나입니다.
Name
preceding_tasks
Type
integer
Description
선행 작업의 수입니다.
이 필드의 값은 작업 상태가 PENDING일 때만 의미가 있습니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시점의 타임스탬프입니다. 밀리초 단위로 표시됩니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시점의 타임스탬프입니다. 밀리초 단위로 표시됩니다. 작업이 아직 시작되지 않은 경우 이 속성은 0이 됩니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 시점의 타임스탬프입니다. 밀리초 단위로 표시됩니다. 작업이 아직 완료되지 않은 경우 이 속성은 0이 됩니다.
Name
task_error
Type
object
Description
실패한 작업에 대한 오류 세부사항입니다. 전체 task_error 객체 참조는 오류를 참조하세요.
Name
consumed_credits
Type
integer
Description
이 작업에 의해 소비된 크레딧의 수입니다. 작업 상태가 PENDING, IN_PROGRESS, 또는 SUCCEEDED일 때 존재합니다. FAILED 작업의 경우 0을 반환합니다 (실패 시 크레딧은 환불됩니다).

예제 리메시 작업 객체

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}