멀티 이미지로 3D API

멀티 이미지로 3D API는 Meshy의 멀티 이미지를 3D로 변환하는 기능을 여러분의 애플리케이션에 통합할 수 있게 해주는 기능입니다. 이 섹션에서는 이 API를 시작하는 데 필요한 모든 정보를 확인할 수 있습니다.

POST/openapi/v1/multi-image-to-3d

멀티 이미지로 3D 태스크 생성

이 엔드포인트를 사용하면 새로운 멀티 이미지로 3D 태스크를 생성할 수 있습니다. 멀티 이미지로 3D 태스크 객체에 어떤 속성이 포함되는지는 멀티 이미지로 3D 태스크 객체를 참조하세요.

파라미터

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

Name
input_task_id
Type
string
필수
Description
완료된 이미지 생성 태스크의 ID로, 해당 출력(1~4개 이미지)이 입력으로 사용됩니다. 이 태스크는 다음 태스크 중 하나여야 합니다: 텍스트로 이미지, 이미지로 이미지, 텍스트로 이미지 멀티뷰 또는 이미지로 이미지 멀티뷰. 또한 API를 통해 실행되었으며 상태가 SUCCEEDED여야 합니다.

Name
image_urls
Type
array
필수
Description
Meshy가 모델 생성에 사용할 1~4개의 이미지를 제공합니다. 현재 .jpg, .jpeg, .png 형식을 지원합니다. 최상의 결과를 위해 모든 이미지는 동일한 객체를 서로 다른 각도에서 촬영한 것이어야 합니다.
각 이미지를 제공하는 방법은 두 가지가 있습니다:
- 공개적으로 접근 가능한 URL: 공용 인터넷에서 접근할 수 있는 URL.
- Data URI: 이미지의 base64로 인코딩된 Data URI. Data URI 예시: data:image/jpeg;base64,<your base64-encoded image data>.
meshy-7(또는 latest)의 경우 첫 번째 이미지가 주요(정면) 뷰로 사용됩니다. 나머지 이미지의 순서는 중요하지 않습니다.

Name
ai_model
Type
string
기본값 latest
Description
사용할 모델의 ID. 사용 가능한 값: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
should_texture
Type
boolean
기본값 true
Description
텍스처를 생성할지 결정합니다. false로 설정하면 텍스처 단계를 건너뛰고 텍스처가 없는 메시를 제공합니다.

다음 경우에만 적용 should_texture = true

Name
enable_pbr
Type
boolean
기본값 false
Description
기본 색상 외에 PBR 맵(메탈릭, 러프니스, 노멀)을 생성합니다. ai_model이 meshy-6인 경우 방출(emission) 맵도 포함되지만, texture_resolution: 8k에서는 제외됩니다. meshy-7과 latest는 방출 맵을 생성하지 않습니다.
Name
texture_resolution
Type
string
기본값 2k
Description
기본 색상 텍스처의 해상도. 2k (2048×2048), 4k (4096×4096), 8k (8192×8192) 중 하나입니다. 해상도가 높을수록 더 많은 표면 디테일을 담아냅니다.
4k와 8k는 ai_model이 meshy-6, meshy-7 또는 latest여야 합니다. 8k에서는 방출 맵이 생성되지 않습니다.
Name
hd_texture
Type
boolean
⚠ 사용 중단
기본값 false
Description
대신 texture_resolution을 사용하세요 — texture_resolution: "4k"와 동일합니다. 둘 다 설정된 경우 texture_resolution이 우선합니다.
Name
texture_prompt
Type
string
Description
텍스처링 과정을 안내할 텍스트 프롬프트를 제공합니다. 최대 600자.
Name
texture_image_url
Type
string
Description
텍스처링 과정을 안내할 2D 이미지를 제공합니다. 현재 .jpg, .jpeg, .png 형식을 지원합니다.
이미지를 제공하는 방법은 두 가지가 있습니다:
- 공개적으로 접근 가능한 URL: 공용 인터넷에서 접근할 수 있는 URL
- Data URI: 이미지의 base64로 인코딩된 Data URI. Data URI 예시: data:image/jpeg;base64,<your base64-encoded image data>
원본 에셋과 업로드한 이미지 사이에 지오메트리 차이가 큰 경우 이미지 텍스처링이 최적으로 동작하지 않을 수 있습니다. 텍스처링 과정을 안내하는 데는 texture_image_url 또는 texture_prompt 중 하나만 사용할 수 있습니다. 두 파라미터가 모두 제공되면 기본적으로 texture_prompt를 사용하여 모델을 텍스처링합니다.

Name
should_remesh
Type
boolean
기본값 false (meshy-6), true (others)
Description
리메시 단계를 활성화할지 여부를 제어합니다. 최고 품질의 모델을 원한다면 should_remesh를 false로 설정하는 것을 권장합니다.

다음 경우에만 적용 should_remesh = true

Name
topology
Type
string
기본값 triangle
Description
생성되는 모델의 토폴로지를 지정합니다.
사용 가능한 값:
- 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
save_pre_remeshed_model
Type
boolean
기본값 false
Description
true로 설정하면 Meshy는 리메시 단계가 완료되기 전의 GLB 파일도 추가로 저장합니다.

Name
symmetry_mode
Type
string
⚠ 사용 중단
기본값 auto
Description
지원 중단되었습니다. 이 파라미터는 더 이상 출력에 영향을 주지 않습니다.
symmetry_mode 필드는 모델 생성 과정에서의 대칭 동작을 제어합니다.
유효한 값은 다음과 같습니다:
- off: 대칭을 비활성화합니다.
- auto: 입력 지오메트리를 기반으로 대칭을 자동으로 판단하여 적용합니다.
- on: 생성 중 대칭을 강제합니다.
Name
pose_mode
Type
string
기본값 ""
Description
생성되는 모델의 포즈 모드를 지정합니다.
사용 가능한 값:
- a-pose: A 포즈로 모델을 생성합니다.
- t-pose: T 포즈로 모델을 생성합니다.
- "" (빈 문자열): 특정 포즈를 적용하지 않습니다.
Name
is_a_t_pose
Type
boolean
⚠ 사용 중단
기본값 false
Description
대신 pose_mode를 사용하세요. 모델을 A/T 포즈로 생성할지 여부입니다.
Name
image_enhancement
Type
boolean
기본값 true
Description
더 나은 결과를 위해 입력 이미지를 최적화합니다. 스타일 처리 없이 입력 이미지의 외형을 그대로 유지하려면 false로 설정하세요.
ai_model이 meshy-6, meshy-7 또는 latest인 경우에만 지원됩니다.
Name
remove_lighting
Type
boolean
기본값 true
Description
기본 색상 텍스처에서 하이라이트와 그림자를 제거하여, 사용자 지정 조명 환경에서 더 잘 어울리는 깔끔한 결과를 만듭니다.
ai_model이 meshy-6, meshy-7 또는 latest인 경우에만 지원됩니다.
Name
moderation
Type
boolean
기본값 false
Description
true로 설정하면 입력 콘텐츠에 유해할 수 있는 내용이 있는지 자동으로 검사합니다. 유해한 콘텐츠가 감지되면 태스크는 생성 단계로 진행되지 않습니다.
image_urls의 각 이미지와 texture_prompt의 텍스트가 검사 대상입니다.
Name
target_formats
Type
string[]
Description
출력에 포함할 3D 파일 형식을 지정합니다. 요청한 형식만 생성 및 반환되므로 태스크 완료 시간을 단축할 수 있습니다.
사용 가능한 값: glb, obj, fbx, stl, usdz, 3mf
생략하면 3mf를 제외한 모든 형식이 생성됩니다. 3mf는 명시적으로 지정한 경우에만 포함됩니다.
Name
auto_size
Type
boolean
기본값 false
Description
true로 설정하면 서비스가 AI 비전을 사용해 객체의 실제 높이를 자동으로 추정하고 그에 맞게 모델 크기를 조정합니다. origin_at을 명시적으로 설정하지 않으면 원점은 기본적으로 bottom이 됩니다.
Name
alpha_thumbnail
Type
boolean
기본값 false
Description
true로 설정하면 태스크가 미리보기의 투명 배경(RGBA) 버전을 추가로 렌더링하여 GET 응답의 alpha_thumbnail_url로 반환합니다. 기존 thumbnail_url 필드는 변경되지 않습니다.
Name
multi_view_thumbnails
Type
boolean
기본값 false
Description
true로 설정하면 태스크가 네 가지 기본 방향의 썸네일(정면, 오른쪽, 후면, 왼쪽)을 추가로 렌더링하여 GET 응답의 thumbnail_urls 아래에 반환합니다. 기존 thumbnail_url 필드는 변경되지 않으며 계속해서 정면 뷰를 가리키므로 기존 클라이언트는 영향을 받지 않습니다.
태스크 지연 시간이 약 3초 증가합니다.

다음 경우에만 적용 auto_size = true

Name
origin_at
Type
string
기본값 bottom
Description
auto_size가 활성화된 경우 원점의 위치. 사용 가능한 값: bottom, center.

반환값

응답의 result 속성에는 새로 생성된 멀티 이미지로 3D 태스크의 태스크 id가 포함됩니다.

실패 모드

Name
400 - Bad Request
Description
요청을 처리할 수 없습니다. 일반적인 원인:
- 파라미터 누락: image_urls 또는 input_task_id 중 하나는 반드시 제공해야 합니다.
- 유효하지 않은 입력 태스크: input_task_id는 SUCCEEDED 상태의 텍스트로 이미지, 이미지로 이미지 또는 멀티뷰 변형 태스크를 가리켜야 합니다.
- 유효하지 않은 이미지 개수: image_urls는 1개에서 4개 사이의 이미지를 포함해야 합니다.
- 유효하지 않은 이미지 형식: image_urls의 이미지 중 하나 이상이 지원되지 않는 형식입니다.
- 접근할 수 없는 URL: image_urls 중 하나 이상을 다운로드할 수 없습니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인하세요.
Name
402 - Payment Required
Description
이 태스크를 수행하기에 크레딧이 부족합니다.
Name
429 - Too Many Requests
Description
요청 한도를 초과했습니다.

Request

POST

/openapi/v1/multi-image-to-3d

# 간단한 요청
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ]
  }'

# PBR 텍스처링과 GLB 형식 사용
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ],
    "should_texture": true,
    "enable_pbr": true,
    "target_formats": ["glb"]
  }'

응답

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

GET/openapi/v1/multi-image-to-3d/:id

멀티 이미지로 3D 태스크 조회

이 엔드포인트를 사용하면 유효한 태스크 id로 멀티 이미지로 3D 태스크를 조회할 수 있습니다. 멀티 이미지로 3D 태스크 객체에 어떤 속성이 포함되는지는 멀티 이미지로 3D 태스크 객체를 참조하세요.

파라미터

Name
id
Type
path
Description
조회할 멀티 이미지로 3D 태스크의 고유 식별자.

반환값

응답에는 멀티 이미지로 3D 태스크 객체가 포함됩니다. 자세한 내용은 멀티 이미지로 3D 태스크 객체 섹션을 확인하세요.

Request

GET

/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

응답

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 30
}

DELETE/openapi/v1/multi-image-to-3d/:id

멀티 이미지로 3D 태스크 삭제

이 엔드포인트는 멀티 이미지로 3D 태스크를 관련된 모든 모델 및 데이터와 함께 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 파라미터

Name
id
Type
path
Description
삭제할 멀티 이미지로 3D 태스크의 ID.

반환값

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

Request

DELETE

/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

응답

// 성공 시 200 Ok를 반환합니다.

GET/openapi/v1/multi-image-to-3d

멀티 이미지로 3D 태스크 목록 조회

이 엔드포인트를 사용하면 멀티 이미지로 3D 태스크 목록을 조회할 수 있습니다.

파라미터

선택적 속성

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

반환값

멀티 이미지로 3D 태스크 객체의 페이지네이션된 목록을 반환합니다.

Request

GET

/openapi/v1/multi-image-to-3d

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

응답

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "multi-image-to-3d",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
        "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
        "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
        "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
        "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 30
  }
]

GET/openapi/v1/multi-image-to-3d/:id/stream

멀티 이미지로 3D 태스크 스트리밍

이 엔드포인트는 Server-Sent Events(SSE)를 사용하여 멀티 이미지로 3D 태스크의 실시간 업데이트를 스트리밍합니다.

파라미터

Name
id
Type
path
Description
스트리밍할 멀티 이미지로 3D 태스크의 고유 식별자.

반환값

멀티 이미지로 3D 태스크 객체의 스트림을 Server-Sent Events로 반환합니다.

PENDING 또는 IN_PROGRESS 상태의 태스크는 응답 스트림에 필요한 progress와 status 필드만 포함됩니다.

Request

GET

/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

응답 스트림

// 오류 이벤트 예시
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// 메시지 이벤트 예시는 태스크 진행 상황을 보여줍니다.
// PENDING 또는 IN_PROGRESS 태스크의 경우 응답 스트림에 모든 필드가 포함되지는 않습니다.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-image-to-3d",
  "model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
  "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
  "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
  "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
  "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
  "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
  "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
  "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 30
}

멀티 이미지로 3D 태스크 객체

멀티 이미지로 3D 태스크 객체는 Meshy가 여러 이미지(1개 이상 4개 이하)로부터 3D 모델을 생성하기 위해 추적하는 작업 단위입니다. 이미지는 동일한 객체를 담고 있어야 하며, 서로 다른 뷰나 각도에서 촬영된 것이 이상적입니다. 이 객체는 다음과 같은 속성을 가집니다:

속성

Name
id
Type
string
Description
태스크의 고유 식별자. 구현 세부 사항으로 태스크 ID에 k-sortable UUID를 사용하지만, ID의 형식에 대해 어떠한 가정도 하지 않아야 합니다.
Name
type
Type
string
Description
멀티 이미지로 3D 태스크의 유형. 값은 multi-image-to-3d입니다.
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
  mtl
  Type
  string
  Description
  MTL 파일의 다운로드 가능한 URL로, 텍스처가 있는 경우 OBJ 내보내기와 함께 반환됩니다.
- Name
  stl
  Type
  string
  Description
  STL 파일의 다운로드 가능한 URL.
- Name
  3mf
  Type
  string
  Description
  3MF 파일의 다운로드 가능한 URL. target_formats를 통해 3mf를 요청한 경우에만 존재합니다.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  리메시 이전의 원본 GLB 출력에 대한 다운로드 가능한 URL.
  태스크가 should_remesh: true와 save_pre_remeshed_model: true를 모두 지정하여 생성된 경우에만 사용할 수 있습니다.
Name
thumbnail_url
Type
string
Description
모델 파일의 썸네일 이미지에 대한 다운로드 가능한 URL. thumbnail_urls.front가 존재하는 경우 그것과 동일하며, 하위 호환성을 위해 유지됩니다.
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url의 투명 배경(RGBA) 버전에 대한 다운로드 가능한 URL. 태스크가 alpha_thumbnail: true로 생성되고 투명 미리보기가 정상적으로 렌더링된 경우에만 존재하며, 그렇지 않으면 이 필드는 생략됩니다.
Name
thumbnail_urls
Type
object
Description
생성된 3D 모델의 네 가지 기본 방향 썸네일에 대한 다운로드 가능한 URL. 각 값은 thumbnail_url과 동일한 재질 및 조명으로 렌더링된 512×512 PNG의 서명된 URL입니다. GLB를 다운로드하지 않고도 배치 파이프라인에서 여러 각도의 모델을 미리 보는 데 유용합니다.
태스크가 multi_view_thumbnails: true로 생성되어 SUCCEEDED에 도달한 경우에만 존재합니다. 이전 태스크와 옵트인 없이 생성된 태스크에는 이 필드가 포함되지 않습니다.
- Name
  front
  Type
  string
  Description
  정면 뷰, 수직 축 기준 0° 회전 (thumbnail_url과 동일).
- Name
  right
  Type
  string
  Description
  오른쪽 뷰, 90° 회전.
- Name
  back
  Type
  string
  Description
  후면 뷰, 180° 회전.
- Name
  left
  Type
  string
  Description
  왼쪽 뷰, 270° 회전.
Name
texture_prompt
Type
string
Description
텍스처링 과정을 안내하는 데 사용된 텍스트 프롬프트.
Name
progress
Type
integer
Description
태스크의 진행률. 태스크가 아직 시작되지 않았다면 이 속성은 0입니다. 태스크가 성공하면 100이 됩니다.
Name
started_at
Type
timestamp
Description
태스크가 시작된 시각의 타임스탬프(밀리초). 태스크가 아직 시작되지 않았다면 이 속성은 0입니다.
타임스탬프는 1970년 1월 1일 UTC 이후 경과한 밀리초 수를 나타내며, RFC 3339 표준을 따릅니다. 예를 들어 2023년 9월 1일 금요일 오후 12:00:00 GMT는 1693569600000으로 표현됩니다. 이는 Meshy API의 모든 타임스탬프에 적용됩니다.
Name
created_at
Type
timestamp
Description
태스크가 생성된 시각의 타임스탬프(밀리초).
Name
expires_at
Type
timestamp
Description
태스크 결과가 만료되는 시각의 타임스탬프(밀리초).
Name
finished_at
Type
timestamp
Description
태스크가 완료된 시각의 타임스탬프(밀리초). 태스크가 아직 완료되지 않았다면 이 속성은 0입니다.
Name
status
Type
string
Description
태스크의 상태. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
Name
texture_urls
Type
array
Description
태스크에서 생성된 텍스처 URL 객체의 배열. 일반적으로 여기에는 하나의 텍스처 URL 객체만 포함됩니다. 각 텍스처 URL은 다음과 같은 속성을 가집니다:
- Name
  base_color
  Type
  string
  Description
  기본 색상 맵 이미지의 다운로드 가능한 URL.
- Name
  metallic
  Type
  string
  Description
  메탈릭 맵 이미지의 다운로드 가능한 URL.
  태스크가 enable_pbr: false로 생성된 경우 이 속성은 생략됩니다.
- Name
  normal
  Type
  string
  Description
  노멀 맵 이미지의 다운로드 가능한 URL.
  태스크가 enable_pbr: false로 생성된 경우 이 속성은 생략됩니다.
- Name
  roughness
  Type
  string
  Description
  러프니스 맵 이미지의 다운로드 가능한 URL.
  태스크가 enable_pbr: false로 생성된 경우 이 속성은 생략됩니다.
- Name
  emission
  Type
  string
  Description
  방출 맵 이미지의 다운로드 가능한 URL.
  태스크가 enable_pbr: false로 생성되었거나 ai_model이 meshy-5인 경우 이 속성은 생략됩니다.
Name
preceding_tasks
Type
integer
Description
선행 태스크의 수.
이 필드의 값은 태스크 상태가 PENDING인 경우에만 의미가 있습니다.
Name
task_error
Type
object
Description
실패한 태스크의 오류 세부 정보. 전체 task_error 객체 레퍼런스는 오류를 참조하세요.
Name
consumed_credits
Type
integer
Description
이 태스크가 소비한 크레딧 수. 태스크 상태가 PENDING, IN_PROGRESS 또는 SUCCEEDED일 때 존재합니다. FAILED 태스크의 경우 0을 반환합니다(실패 시 크레딧은 환불됩니다).

멀티 이미지로 3D 태스크 객체 예시

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 30,
}