멀티 이미지로 3D API

서로 다른 각도에서 촬영한 동일한 객체의 이미지 1~4장으로 3D 모델을 생성합니다.

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

멀티 이미지로 3D 작업 생성하기

멀티 이미지로 3D 작업을 생성합니다. 작업은 백그라운드에서 실행됩니다. 작업이 일반적으로 얼마나 걸리는지는 처리 시간을 참고하세요. 작업이 가지는 필드에 대해서는 멀티 이미지로 3D 작업 객체를 참고하세요.

Request

POST

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

# Simple request
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>"
    ]
  }'

# With Ultra 2K geometry, PBR texturing, and GLB format
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>"
    ],
    "ai_model": "meshy-7.1",
    "geometry_resolution": "2k",
    "should_texture": true,
    "enable_pbr": true,
    "target_formats": ["glb"]
  }'

# Textured with Meshy N1 from the input images, the first as the front view
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 front view image url or base64-encoded data URI>",
      "<your back view image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "texture_model": "meshy-n1"
  }'

Response

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

파라미터

Name
input_task_id
Type
string
필수
Description
image_urls를 보내지 않는 경우 필수입니다. 텍스트로 이미지 또는 이미지로 이미지 작업(멀티뷰 작업 포함)의 ID입니다. Meshy는 해당 작업의 1~4개 이미지를 입력으로 사용합니다. 이 작업은 API로 생성했으며 상태가 SUCCEEDED인 작업이어야 합니다.

Name
image_urls
Type
array
필수
Description
input_task_id를 보내지 않는 경우 필수입니다. 공개 URL 또는 data:image/jpeg;base64,<your base64-encoded image data>와 같은 data URI 형태의 이미지 1~4개입니다. 둘 다 보내면 Meshy는 input_task_id를 사용합니다.
각 이미지는 최대 20MB 크기의 .jpg, .jpeg, .png, .webp 파일이어야 하며, 각 변의 길이가 최소 32픽셀, 최대 178,956,970픽셀(가로 × 세로)이어야 합니다. 이미지가 4개를 초과하면 400이 반환됩니다.
최상의 결과를 얻으려면 이미지는 서로 다른 각도에서 촬영한 동일한 객체를 보여줘야 합니다. meshy-7.1 또는 latest의 경우, Meshy는 첫 번째 이미지를 정면 뷰로 사용하며 나머지 이미지의 순서는 상관없습니다.

Name
ai_model
Type
string
기본값 latest
Description
3D 모델을 생성하는 AI 모델입니다.
사용 가능한 값:
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7: 지원 중단됨, 대신 meshy-7.1을 보내세요
Name
geometry_resolution
Type
string
기본값 standard
Description
생성할 지오메트리 디테일의 수준입니다.
사용 가능한 값:
- standard
- 2k: 2048³ 해상도로 Ultra 패스를 실행합니다. meshy-7.1, latest, 또는 지원 중단된 meshy-7가 필요합니다.
Name
ultra_mode
Type
boolean
⚠ 사용 중단
기본값 false
Description
대신 geometry_resolution을 보내세요. ultra_mode: true는 geometry_resolution: "2k"와 동일합니다.
Name
should_texture
Type
boolean
기본값 true
Description
텍스처를 생성할지 여부입니다. true는 텍스처가 적용된 모델을 반환하고, false는 텍스처 단계를 건너뛰고 텍스처가 없는 메시를 반환합니다.

다음 경우에만 적용 should_texture = true

Name
texture_model
Type
string
기본값 depends on ai_model
Description
같은 작업 내에서 여러 뷰로부터 3D 모델에 텍스처를 입히는 AI 모델입니다. 생략하면 해당 ai_model의 기본 텍스처 모델을 사용합니다. 크레딧 비용에는 영향을 주지 않습니다.
사용 가능한 값:
- meshy-7: Meshy 7, PBR 맵과 최대 8K 텍스처 지원
- meshy-n1: Meshy N1, 참조 이미지로부터만 생성되는 2K 기본 색상 텍스처
모든 ai_model은 두 값을 모두 받습니다. meshy-6 또는 meshy-6-lite로 텍스처 요청을 보내면 400이 반환되며, 선택한 텍스처 모델이 지원하지 않는 옵션을 보내도 마찬가지입니다. should_texture: false인 경우 Meshy는 texture_model을 무시하지만, 알 수 없는 값을 보내면 여전히 400이 반환됩니다.
meshy-n1의 경우, Meshy는 texture_image_urls 또는 texture_image_url로부터 텍스처를 입히며, 둘 다 보내지 않으면 입력 이미지로부터 텍스처를 입힙니다. 첫 번째 이미지가 정면 뷰입니다. 생성된 모델이 7,999,999 삼각형을 초과하면 작업이 실패하고 Meshy는 크레딧을 환불합니다.
각 텍스처 모델이 수행하는 작업과 선택 기준에 대해서는 모델을 참고하세요.
Name
enable_pbr
Type
boolean
기본값 false
Description
기본 색상 외에 메탈릭, 러프니스, 노멀 맵도 생성할지 여부입니다. Meshy 6 텍스처 모델은 texture_resolution: 8k인 경우를 제외하고 이미션 맵도 생성합니다. texture_model: meshy-n1의 경우 true를 보내면 400이 반환됩니다.
Name
texture_resolution
Type
string
기본값 2k
Description
기본 색상 텍스처의 크기입니다. 크기가 클수록 표면 디테일을 더 많이 담습니다.
사용 가능한 값:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k와 8k는 Meshy 7 또는 Meshy 6 텍스처 모델이 필요하며, 다른 모델에서는 400이 반환됩니다. 8k에서는 Meshy가 이미션 맵을 생성하지 않습니다.
Name
hd_texture
Type
boolean
⚠ 사용 중단
기본값 false
Description
대신 texture_resolution을 보내세요. hd_texture: true는 texture_resolution: "4k"와 동일합니다. 둘 다 보내면 Meshy는 texture_resolution을 사용합니다.
Name
texture_prompt
Type
string
Description
텍스처를 안내하는 텍스트로, 최대 800자까지 가능합니다. 더 긴 텍스트를 보내면 400이 반환됩니다. texture_model: meshy-n1의 경우, 이를 보내면 400이 반환됩니다.
Name
texture_image_url
Type
string
Description
텍스처를 안내하는 하나의 2D 이미지로, 공개 URL 또는 data:image/jpeg;base64,<your base64-encoded image data>와 같은 data URI 형태입니다. 이미지는 최대 20MB 크기의 .jpg, .jpeg, .png, .webp 파일이어야 하며, 각 변의 길이가 최소 32픽셀, 최대 178,956,970픽셀(가로 × 세로)이어야 합니다.
texture_image_url과 texture_prompt를 모두 보내면 Meshy는 texture_prompt를 사용합니다. texture_model: meshy-n1의 경우, Meshy는 이 이미지를 정면 뷰로 사용하여 텍스처를 입힙니다.
이미지 속 형태가 3D 모델과 크게 다른 경우 텍스처가 잘 나오지 않을 수 있습니다.
Name
texture_image_urls
Type
string[]
Description
텍스처를 안내하기 위한, 서로 다른 뷰에서 촬영한 객체 이미지 1~4개입니다. Meshy는 첫 번째 이미지를 정면 뷰로 사용합니다. 나머지 뷰(왼쪽, 뒤, 오른쪽)의 순서는 상관없습니다.
각 이미지는 texture_image_url과 동일한 규칙을 따릅니다. 공개 URL 또는 data URI이며, .jpg, .jpeg, .png, .webp 형식이고, 최대 20MB 크기이며, 각 변의 길이가 최소 32픽셀, 최대 178,956,970픽셀(가로 × 세로)입니다.
이 이미지들은 텍스처만 안내하며 image_urls에 의존하지 않습니다. 두 목록은 서로 다른 이미지와 서로 다른 수의 이미지를 가질 수 있습니다.
texture_image_urls는 Meshy 7 또는 Meshy N1 텍스처 모델이 필요합니다. 다음 중 하나와 함께 보내세요:
- meshy-7.1, latest, 또는 지원 중단된 meshy-7의 ai_model
- meshy-7 또는 meshy-n1의 texture_model
texture_image_url 또는 texture_prompt와 함께 보낼 수는 없습니다.

Name
should_remesh
Type
boolean
기본값 true (meshy-6-lite), false (other models)
Description
생성 후 모델을 리메시할지 여부입니다. 최고 품질의 3D 모델을 원하면 false로 설정하세요.

다음 경우에만 적용 should_remesh = true

Name
topology
Type
string
기본값 triangle
Description
리메시된 모델의 면 유형입니다.
사용 가능한 값:
- quad: 쿼드가 주를 이루는 메시
- triangle: 간략화된 삼각형 메시
texture_model: meshy-n1의 경우, 모델이 리메시되면 quad는 400을 반환하며, meshy-6-lite는 기본적으로 리메시를 수행합니다.
Name
target_polycount
Type
integer
기본값 30000
Description
목표로 할 면의 개수로, 100에서 300000 사이입니다. 결과는 모델의 지오메트리에 따라 목표값과 다를 수 있습니다. 범위를 벗어난 값을 보내면 400이 반환됩니다.
Name
decimation_mode
Type
integer
Description
레벨별 적응형 면 개수입니다. 이 값을 설정하면 Meshy는 target_polycount를 무시합니다.
사용 가능한 값:
- 1: 울트라
- 2: 높음
- 3: 중간
- 4: 낮음
Name
save_pre_remeshed_model
Type
boolean
기본값 false
Description
리메시 전의 GLB도 저장할지 여부이며, model_urls.pre_remeshed_glb로 반환됩니다.

Name
symmetry_mode
Type
string
⚠ 사용 중단
기본값 auto
Description
생략하세요. 출력에 영향을 주지 않습니다.
사용 가능한 값:
- 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는 스타일 처리 없이 입력 이미지의 모습을 그대로 유지합니다. meshy-6, meshy-7.1, 또는 latest에서만 지원됩니다. meshy-6-lite와 함께 보내면 400이 반환됩니다.
Name
remove_lighting
Type
boolean
기본값 true
Description
기본 색상 텍스처에서 하이라이트와 그림자를 제거할지 여부입니다. 더 깔끔한 결과는 사용자 자신의 조명 환경에서 더 잘 작동합니다. Meshy 6 텍스처 모델만 이를 사용하며, texture_resolution: 8k에서는 항상 조명을 제거합니다. texture_model: meshy-n1의 경우 true를 보내면 400이 반환됩니다. ai_model: meshy-6-lite와 그 기본 텍스처 모델의 경우, 이를 보내면 400이 반환됩니다.
Name
moderation
Type
boolean
기본값 false
Description
입력에 유해한 콘텐츠가 있는지 검사할지 여부입니다. Meshy는 각 입력 이미지, texture_image_url 또는 texture_image_urls의 각 이미지, 그리고 texture_prompt의 텍스트를 검사합니다. Meshy가 유해한 콘텐츠를 발견하면 요청은 400을 반환하며 Meshy는 작업을 생성하지 않습니다.
Name
target_formats
Type
string[]
Description
생성할 3D 파일 형식입니다. Meshy는 목록에 지정한 형식만 생성하여 반환하며, 이를 통해 작업 시간을 단축할 수 있습니다.
사용 가능한 값:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
생략하면 Meshy는 3mf를 제외한 모든 형식을 생성합니다. Meshy는 목록에 3mf를 지정한 경우에만 이를 생성합니다.
Name
auto_size
Type
boolean
기본값 false
Description
AI 비전으로 객체의 실제 높이를 추정하고 모델을 그 크기로 조정할지 여부입니다. origin_at을 설정하지 않으면 Meshy는 원점을 바닥에 둡니다.

다음 경우에만 적용 auto_size = true

Name
origin_at
Type
string
기본값 bottom
Description
모델의 원점을 둘 위치로, bottom 또는 center입니다.

Name
alpha_thumbnail
Type
boolean
기본값 false
Description
배경이 투명한(RGBA) 미리보기도 렌더링할지 여부이며, 작업을 조회할 때 alpha_thumbnail_url로 반환됩니다. thumbnail_url은 변경되지 않습니다.
Name
multi_view_thumbnails
Type
boolean
기본값 false
Description
정면, 오른쪽, 뒤, 왼쪽 미리보기도 렌더링할지 여부이며, 작업을 조회할 때 thumbnail_urls로 반환됩니다. thumbnail_url은 변경되지 않으며 여전히 정면 뷰를 보여줍니다. 이 옵션은 작업 시간을 약 5초 늘립니다.

반환값

응답의 result 필드는 새로 생성된 멀티 이미지로 3D 작업의 ID를 담고 있습니다.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 오류 메시지가 어떤 문제를 발견했는지 알려줍니다. 예를 들면:
- 파라미터 누락: image_urls와 input_task_id 모두 보내지 않았습니다.
- 잘못된 입력 작업: input_task_id가 SUCCEEDED 상태의 텍스트로 이미지 또는 이미지로 이미지 작업, 또는 멀티뷰 작업이 아닙니다.
- 잘못된 이미지 개수: image_urls 또는 texture_image_urls에 이미지가 1~4개 범위로 들어있지 않습니다.
- 잘못된 이미지 형식: image_urls의 이미지가 지원되는 형식이 아닙니다.
- 상충하는 텍스처 입력: texture_image_urls가 texture_image_url, texture_prompt, 또는 should_texture: false와 함께 전송되었습니다.
- 멀티뷰 텍스처에 지원되지 않는 모델: texture_image_urls가 meshy-6 또는 meshy-6-lite의 ai_model과 함께 전송되었으며, texture_model이 meshy-7 또는 meshy-n1이 아닙니다.
- 접근할 수 없는 URL: Meshy가 image_urls 또는 texture_image_urls의 이미지를 다운로드할 수 없습니다.
- 이미지가 너무 큼: image_urls, texture_image_url, 또는 texture_image_urls의 이미지가 20MB를 초과합니다.
- 잘못된 이미지 크기: image_urls, texture_image_url, 또는 texture_image_urls의 이미지가 한 변이 32픽셀보다 짧거나, 178,956,970픽셀(가로 × 세로)을 초과합니다.
- 멀티 이미지 입력에 지원되지 않는 해상도: geometry_resolution이 "4k"이며, 이 엔드포인트는 이를 지원하지 않습니다. 2k 또는 standard를 사용하세요.
- 이미지 옵션에 지원되지 않는 모델: ai_model: "meshy-6-lite"와 함께 image_enhancement가 전송되었거나, ai_model: "meshy-6-lite"와 그 기본 텍스처 모델과 함께 remove_lighting이 전송되었습니다.
- 잘못된 텍스처 모델: texture_model이 유효한 텍스처 모델 이름이 아닙니다.
- 텍스처 모델을 사용할 수 없음: 텍스처 요청에서 texture_model로 meshy-6 또는 meshy-6-lite가 전송되었습니다. 멀티 이미지로 3D는 여러 뷰로부터 텍스처를 입히는 텍스처 모델만 사용할 수 있습니다. meshy-7 또는 meshy-n1을 보내거나 texture_model을 생략하세요.
- 텍스처 모델에 지원되지 않는 옵션: 요청이 텍스처 모델이 지원하지 않는 옵션을 요청했습니다. 예를 들어 meshy-n1과 함께 enable_pbr: true를 보내거나, meshy-6-lite와 함께 4k 텍스처를 요청한 경우입니다. 모델을 참고하세요.
요청을 수정한 뒤 다시 보내세요. 오류를 참고하세요.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
예를 들면:
- 크레딧 부족: 계정에 이 작업을 수행할 만큼 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. 크레딧 잔액을 확인한 뒤 다시 시도하세요.
- 무료 플랜: 작업을 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 뒤 다시 시도하세요.
Name
403 - Forbidden
Description
콘텐츠 검열에 의해 prompt 또는 입력 이미지가 차단되었습니다. 입력을 변경한 뒤 다시 시도하세요.
Name
404 - Not Found
Description
input_task_id가 회원님의 어떤 작업과도 일치하지 않습니다. 작업 ID를 확인한 뒤 요청을 다시 보내세요.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다. 잠시 기다린 뒤 다시 시도하세요. 속도 제한을 참고하세요.

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

멀티 이미지로 3D 작업 가져오기

ID로 멀티 이미지로 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}"

Response

{
  "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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

파라미터

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

반환 값

멀티 이미지로 3D 작업 객체를 반환합니다.

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

멀티 이미지로 3D 작업 삭제

멀티 이미지로 3D 작업을 모델 및 데이터를 포함하여 영구적으로 삭제합니다. 삭제는 취소할 수 없습니다.

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

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, 또는 CANCELED 상태에 도달할 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)의 작업을 삭제해도 크레딧은 환불되지 않습니다.

반환값

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

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

멀티 이미지로 3D 작업 목록 조회

사용자의 멀티 이미지로 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}"

Response

[
  {
    "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"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 30
  }
]

매개변수

Name
page_num
Type
integer
기본값 1
Description
반환할 페이지 번호이며, 최대 255까지 가능합니다. 더 큰 값을 지정하면 400을 반환합니다.
Name
page_size
Type
integer
기본값 10
Description
페이지당 작업 수이며, 최대 100까지 가능합니다.
Name
sort_by
Type
string
Description
정렬 순서입니다.
사용 가능한 값:
- +created_at: 오래된 순
- -created_at: 최신 순

반환값

멀티 이미지로 3D 작업 객체의 페이지네이션된 목록입니다.

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

멀티 이미지로 3D 작업 스트리밍

멀티 이미지로 3D 작업의 업데이트를 서버 전송 이벤트(SSE)로 스트리밍합니다.

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

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

파라미터

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

반환값

멀티 이미지로 3D 작업 객체의 스트림을 서버 전송 이벤트로 반환합니다.

각 이벤트는 Get 엔드포인트가 반환하는 것과 동일한 형태로 전체 작업 객체를 담고 있습니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 결과 필드에 아직 값이 없습니다.

The Multi-Image to 3D task object

Multi-Image to 3D 작업 객체는 1~4개의 이미지로부터 3D 모델을 생성하는 하나의 작업을 설명합니다. 여기에는 상태, progress, 그리고 작업이 성공했을 때의 모델 파일이 담겨 있습니다.

속성

Example Multi-Image to 3D Task Object

{
  "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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Name
id
Type
string
Description
작업 ID입니다. 불투명한 문자열로 취급하고, 그 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형이며, 항상 multi-image-to-3d입니다.
Name
model_urls
Type
object
Description
생성된 3D 모델의 다운로드 URL이며, 파일 형식마다 하나씩 있습니다. 작업이 생성하지 않은 형식은 빈 문자열이 아니라 키 자체가 없습니다.
- Name
  glb
  Type
  string
  Description
  GLB 파일입니다.
- Name
  fbx
  Type
  string
  Description
  FBX 파일입니다.
- Name
  obj
  Type
  string
  Description
  OBJ 파일입니다.
- Name
  usdz
  Type
  string
  Description
  USDZ 파일입니다.
- Name
  mtl
  Type
  string
  Description
  MTL 파일이며, 모델에 텍스처가 있을 때 OBJ 파일과 함께 반환됩니다.
- Name
  stl
  Type
  string
  Description
  STL 파일입니다.
- Name
  3mf
  Type
  string
  Description
  3MF 파일입니다. target_formats에 3mf가 포함된 경우에만 존재합니다.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  리메시 이전의 GLB 파일입니다. 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로 작업을 생성하고 Meshy가 투명 미리보기를 렌더링한 경우에만 존재합니다.
Name
thumbnail_urls
Type
object
Description
3D 모델을 네 방향에서 바라본 미리보기를 위한 다운로드 URL입니다. 각각은 512×512 PNG에 대한 서명된 URL이며, thumbnail_url과 동일한 재질 및 조명으로 렌더링됩니다. GLB 파일을 다운로드하지 않고도 여러 각도에서 모델을 미리볼 때 사용할 수 있습니다.
multi_view_thumbnails: true로 작업을 생성하고 작업이 SUCCEEDED에 도달한 경우에만 존재합니다. multi_view_thumbnails: true 없이 생성한 작업에는 이 필드가 없습니다.
- 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
텍스처를 유도한 텍스트 prompt입니다.
Name
texture_image_urls
Type
string[]
Description
작업을 생성할 때 사용한 텍스처 참조 이미지의 다운로드 URL이며, 전송한 순서대로 나열됩니다. texture_image_urls로 작업을 생성한 경우에만 존재합니다.
Name
ultra_mode
Type
boolean
⚠ 사용 중단
Description
대신 geometry_resolution을 참조하세요.
Name
geometry_resolution
Type
string
Description
작업이 실행된 Ultra 등급이며, 2k입니다. standard 작업에는 이 필드가 없습니다.
Name
progress
Type
integer
Description
작업이 완료된 정도를 백분율로 나타낸 값입니다. 작업이 시작되기 전까지는 0이고, 성공하면 100입니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시각이며, Unix 밀리초 단위입니다. 작업이 시작되기 전까지는 0입니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시각이며, Unix 밀리초 단위입니다.
Name
expires_at
Type
timestamp
Description
작업 결과가 만료되는 시각이며, Unix 밀리초 단위입니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 시각이며, Unix 밀리초 단위입니다. 작업이 완료되기 전까지는 0입니다.
Name
status
Type
string
Description
작업 상태이며, PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
Name
texture_urls
Type
array
Description
작업이 생성한 텍스처 맵의 다운로드 URL이며, 객체 배열 형태입니다. 보통 객체 하나를 담고 있습니다. 각 객체는 다음 필드를 가집니다:
- Name
  base_color
  Type
  string
  Description
  베이스 컬러 맵입니다.
- Name
  metallic
  Type
  string
  Description
  메탈릭 맵입니다. enable_pbr: false로 작업을 생성한 경우에는 포함되지 않습니다.
- Name
  normal
  Type
  string
  Description
  노멀 맵입니다. enable_pbr: false로 작업을 생성한 경우에는 포함되지 않습니다.
- Name
  roughness
  Type
  string
  Description
  러프니스 맵입니다. enable_pbr: false로 작업을 생성한 경우에는 포함되지 않습니다.
- Name
  emission
  Type
  string
  Description
  이미션 맵입니다. 다음 조건을 모두 충족하여 작업을 생성한 경우에만 포함됩니다:
  
  ai_model: meshy-6과 그 기본 텍스처 모델
  
  enable_pbr: true
  
  2k 또는 4k의 texture_resolution
Name
preceding_tasks
Type
integer
Description
대기열에서 이 작업보다 앞서 있는 작업의 수입니다. 이 값은 작업이 PENDING 상태일 때만 의미가 있습니다.
Name
task_error
Type
object
Description
작업이 실패했을 때의 오류 세부 정보입니다. 상태가 FAILED가 아닌 한 null입니다. 오류를 참조하세요.
Name
consumed_credits
Type
integer
Description
작업이 사용한 크레딧 수입니다. 상태가 PENDING, IN_PROGRESS, SUCCEEDED일 때 존재합니다. 작업이 실패하면 Meshy가 크레딧을 환불하므로 FAILED 작업의 경우 0입니다.