이미지로 3D API

이미지를 텍스처가 적용된 또는 적용되지 않은 3D 모델로, 원하는 형식으로 변환하세요. 이미지를 전송하거나 텍스트로 이미지 또는 이미지로 이미지 작업의 결과물을 사용할 수 있습니다.

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

Image to 3D 작업 생성

Image to 3D 작업을 생성합니다. 작업은 백그라운드에서 실행됩니다. 작업이 일반적으로 얼마나 걸리는지는 처리 시간을 참고하세요.

Request

POST

/openapi/v1/image-to-3d

# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -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>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -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>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

# Textured with Meshy N1 from the input image
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -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>",
    "ai_model": "meshy-7.1",
    "texture_model": "meshy-n1"
  }'

Response

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

파라미터

Name
input_task_id
Type
string
필수
Description
image_url을 보내지 않는 한 필수입니다. 입력으로 사용할 이미지를 생성한 텍스트로 이미지 또는 이미지로 이미지 작업의 ID입니다. 해당 작업은 API로 생성한 것이어야 하고, 상태가 SUCCEEDED여야 하며, 이미지를 정확히 하나 생성한 것이어야 합니다.

Name
image_url
Type
string
필수
Description
input_task_id를 보내지 않는 한 필수입니다. 공개 URL 또는 base64로 인코딩된 data URI(예: data:image/jpeg;base64,<your base64-encoded image data>) 형태로, 3D 모델로 변환할 이미지입니다. 둘 다 보내면 Meshy는 input_task_id를 사용합니다.
이미지는 최대 20MB 크기의 JPG, JPEG, PNG, WebP 파일이어야 하며, 각 변이 최소 32픽셀 이상이어야 하고, 최대 178,956,970픽셀(너비 × 높이) 이하여야 합니다.

Name
model_type
Type
string
기본값 standard
Description
생성할 3D 메시의 종류입니다.
사용 가능한 값:
- standard: 고디테일 메시
- smart-topology: Smart Topology 모델로 생성한 메시이며, ai_model(meshy-t2 또는 meshy-t2.5)로 선택합니다
smart-topology를 사용하면 Meshy는 should_remesh, save_pre_remeshed_model, decimation_mode를 무시하며, topology: triangle만 허용합니다.
Name
ai_model
Type
string
기본값 latest
Description
3D 모델을 생성하는 AI 모델입니다. 사용 가능한 값은 model_type에 따라 다릅니다.
표준 모델(model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7(지원 중단): 대신 meshy-7.1을 사용하세요
Smart Topology 모델(model_type: smart-topology)은 삼각형을 생성하며, target_polycount로 면 수를 설정할 수 있습니다:
- meshy-t2: 더 깔끔한 topology와 네이티브로 분리된 파츠
- meshy-t2.5(기본값): 게임 에셋에 적합한 더 선명한 디테일
Name
geometry_resolution
Type
string
기본값 standard
Description
지오메트리 생성 패스입니다.
사용 가능한 값:
- standard
- 2k: 2048³로 Ultra 패스 실행
- 4k: 4096³로 Ultra 패스 실행, 가장 디테일한 표면 묘사
2k는 meshy-7.1, latest, 또는 지원 중단된 meshy-7이 필요합니다. 4k는 meshy-7.1 또는 latest가 필요합니다.
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 베이스 컬러 텍스처
- meshy-6-lite: Meshy 6 Lite, 최저 비용의 2K 텍스처
- meshy-6: Meshy 6, ai_model: meshy-6의 기본값으로만 사용 가능
모든 ai_model은 meshy-7, meshy-n1, meshy-6-lite를 사용할 수 있습니다. 선택한 텍스처 모델이 지원하지 않는 옵션을 요청하면 400이 반환됩니다. meshy-n1을 사용할 때 생성된 모델이 7,999,999 삼각형을 초과하면 작업이 실패하며, Meshy는 해당 크레딧을 환불합니다. should_texture: false인 경우 Meshy는 texture_model을 무시하지만, 알 수 없는 값을 보내면 여전히 400을 반환합니다.
각 텍스처 모델이 수행하는 작업과 선택 기준은 모델을 참고하세요.
Name
enable_pbr
Type
boolean
기본값 false
Description
베이스 컬러 외에 PBR 맵(메탈릭, 러프니스, 노멀)도 생성할지 여부입니다. true로 설정하려면 should_texture: true가 필요하며, should_texture: false일 때는 400을 반환합니다. texture_model: meshy-n1일 때 true로 설정하면 400을 반환합니다.
Meshy 6 텍스처 모델은 texture_resolution: 8k인 경우를 제외하고 이미션 맵도 생성합니다.
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
텍스처를 안내하는 이미지로, 공개 URL 또는 base64로 인코딩된 data URI(예: data:image/jpeg;base64,<your base64-encoded image data>) 형태입니다. 이미지는 최대 20MB 크기의 JPG, JPEG, PNG, WebP 파일이어야 하며, 각 변이 최소 32픽셀 이상이어야 하고, 최대 178,956,970픽셀(너비 × 높이) 이하여야 합니다.
Meshy는 texture_prompt와 texture_image_url 중 하나만으로 텍스처를 안내합니다. 둘 다 보내면 Meshy는 texture_prompt를 사용합니다. 텍스처링의 크레딧 비용은 요금을 참고하세요.
texture_model: meshy-n1인 경우, Meshy는 이 이미지를 정면 뷰로 사용하여 텍스처링하며, 생략하면 입력 이미지를 사용합니다.
이미지의 형태가 3D 모델의 지오메트리와 많이 다르면 이미지로부터의 텍스처링이 잘 동작하지 않을 수 있습니다.

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: 간소화된 삼각형 메시
Smart Topology 출력은 삼각형만 지원하므로, meshy-t2 또는 meshy-t2.5에서 quad를 사용하면 400을 반환합니다. texture_model: meshy-n1일 때, 모델이 리메시되는 경우(meshy-6-lite는 기본적으로 리메시됨) quad는 400을 반환합니다.
Name
decimation_mode
Type
integer
Description
레벨별 적응형 면 수입니다. 이 값을 설정하면 Meshy는 target_polycount를 무시합니다.
사용 가능한 값:
- 1: 울트라
- 2: 높음
- 3: 중간
- 4: 낮음
Name
save_pre_remeshed_model
Type
boolean
기본값 false
Description
리메시 단계 이전 모델의 GLB도 저장할지 여부입니다. Meshy는 이를 model_urls.pre_remeshed_glb로 반환합니다.

Name
target_polycount
Type
integer
Description
목표로 할 면의 개수입니다. 모델의 지오메트리에 따라 실제 결과는 목표치와 다를 수 있습니다.
이 값은 두 가지 경우에 각각 적용됩니다:
- 리메시: standard 모델에서 should_remesh가 true일 때, Meshy는 이 개수에 맞춰 메시를 간소화합니다. decimation_mode를 설정하면 Meshy는 이를 사용하고 target_polycount는 무시합니다.
- Smart Topology: model_type이 smart-topology이고 ai_model이 meshy-t2 또는 meshy-t2.5일 때, Meshy는 이 면 수로 모델을 생성합니다. 리메시는 실행되지 않으며 should_remesh는 필요하지 않습니다.
범위와 기본값은 경우에 따라 다릅니다:
경우 범위 기본값
리메시 100 ~ 300000 30000
meshy-t2 100 ~ 15000 4000
meshy-t2.5 100 ~ 30000 15000
범위를 벗어나는 값은 400을 반환합니다.

경우	범위	기본값
리메시	`100` ~ `300000`	`30000`
`meshy-t2`	`100` ~ `15000`	`4000`
`meshy-t2.5`	`100` ~ `30000`	`15000`

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
surface_mode
Type
string
⚠ 사용 중단
Description
대신 ai_model을 사용하세요. 이 값이 선택하던 모델 생성 방식은 폐기되었으므로 출력에 영향을 주지 않습니다.
허용되는 값은 organic과 hard입니다. 다른 값은 400을 반환합니다.
Name
image_enhancement
Type
boolean
기본값 true
Description
생성 전에 입력 이미지를 최적화할지 여부입니다. false이면 스타일 처리 없이 입력 이미지의 모습을 그대로 유지합니다.
meshy-6, meshy-7.1, 또는 latest에서만 동작합니다. meshy-6-lite 또는 model_type: smart-topology에서는 400을 반환합니다.
Name
remove_lighting
Type
boolean
기본값 true
Description
베이스 컬러 텍스처에서 하이라이트와 그림자를 제거할지 여부입니다. 결과가 더 깔끔해지고 자체 조명 환경에서 더 잘 어울립니다.
Meshy 6 텍스처 모델에서만 적용되며, 이를 지원하지 않는 텍스처 모델에서 true로 설정하면 400을 반환합니다. model_type: smart-topology인 경우, 또는 ai_model: meshy-6-lite와 그 기본 텍스처 모델인 경우, 이 값을 보내면 400을 반환합니다.
Name
moderation
Type
boolean
기본값 false
Description
생성 전에 다음 입력의 유해 콘텐츠 여부를 검사할지 여부입니다:
- image_url
- texture_image_url
- texture_prompt
Meshy가 유해 콘텐츠를 감지하면 요청은 400을 반환하며 Meshy는 작업을 생성하지 않습니다.
Name
target_formats
Type
string[]
Description
생성할 파일 형식입니다. Meshy는 나열된 형식만 생성하여 반환하며, 이를 통해 작업 시간을 단축할 수 있습니다. 생략하면 Meshy는 3mf를 제외한 모든 형식을 생성하며, 3mf는 나열했을 때만 얻을 수 있습니다.
사용 가능한 값:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
기본값 false
Description
AI 비전으로 객체의 실제 높이를 추정하여 모델 크기를 그에 맞게 조정할지 여부입니다. origin_at을 설정하지 않으면 Meshy는 원점을 바닥에 둡니다.
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초 늘립니다.

다음 경우에만 적용 auto_size = true

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

반환값

응답의 result 필드에는 새로 생성된 Image to 3D 작업의 ID가 들어 있습니다.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 오류 메시지는 어떤 문제가 발견되었는지 알려줍니다. 예를 들어:
- 파라미터 누락: image_url과 input_task_id 둘 다 보내지 않았습니다.
- 잘못된 입력 작업: input_task_id가 이미지를 정확히 하나 생성한 SUCCEEDED 상태의 텍스트로 이미지 또는 이미지로 이미지 작업이 아닙니다.
- 잘못된 이미지 형식: image_url 이미지가 JPG, JPEG, PNG, WebP 파일이 아닙니다.
- 접근 불가능한 URL: URL이 404를 반환하거나 시간이 초과되어 Meshy가 image_url 이미지를 다운로드할 수 없습니다.
- 이미지가 너무 큼: image_url 또는 texture_image_url 이미지가 20MB를 초과합니다.
- 잘못된 이미지 크기: image_url 또는 texture_image_url 이미지의 한 변이 32픽셀보다 짧거나, 178,956,970픽셀(너비 × 높이)을 초과합니다.
- 잘못된 data URI: base64 문자열 형식이 올바르지 않습니다.
- 잘못된 파라미터 조합: enable_pbr이 true이고 should_texture가 false입니다.
- Ultra에서 지원하지 않는 모델: geometry_resolution이 2k 또는 4k인데, 해당 ai_model이 이를 실행할 수 없습니다.
- 이미지 옵션에서 지원하지 않는 모델: 다음 중 하나:
  - ai_model: "meshy-6-lite" 또는 model_type: "smart-topology"와 함께 image_enhancement를 보냈습니다.
  - model_type: "smart-topology"와 함께, 또는 ai_model: "meshy-6-lite"와 그 기본 텍스처 모델과 함께 remove_lighting을 보냈습니다.
- 잘못된 텍스처 모델: texture_model이 사용 가능한 값 중 하나가 아닙니다.
- 사용할 수 없는 텍스처 모델: texture_model이 meshy-6인데 ai_model이 meshy-6이 아닙니다. meshy-7, meshy-n1, meshy-6-lite를 보내거나 생략하세요.
- 텍스처 모델에서 지원하지 않는 옵션: 요청이 텍스처 모델이 지원하지 않는 옵션을 요구합니다. 예를 들어 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/image-to-3d/:id

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

ID로 이미지로 3D 작업을 반환합니다.

Request

GET

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

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "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": null,
  "consumed_credits": 30
}

매개변수

Name
id
Type
path
Description
생성 응답에서 제공된 작업 ID입니다.

반환값

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

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

Image to 3D 작업 삭제

Image to 3D 작업을 모델 및 데이터와 함께 영구적으로 삭제합니다. 삭제는 되돌릴 수 없습니다.

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/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/image-to-3d

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

사용자의 이미지로 3D 작업 목록을 반환합니다.

Request

GET

/openapi/v1/image-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "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": 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/image-to-3d/:id/stream

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

이미지로 3D 작업의 업데이트를 Server-Sent Events (SSE)로 스트리밍합니다.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/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": "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": null,
  "consumed_credits": 30
}

매개변수

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

반환값

이미지로 3D 작업 객체를 Server-Sent Events 형태의 스트림으로 반환합니다.

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

이미지로 3D 작업 객체

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

속성

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "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": "",
  "texture_image_url": "",
  "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": null,
  "consumed_credits": 30
}

Name
id
Type
string
Description
작업 ID입니다. 불투명한 문자열로 취급하고, 그 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형이며, 항상 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
3D 모델 미리보기 이미지의 다운로드 URL입니다. thumbnail_urls가 있는 경우 thumbnail_urls.front와 동일한 이미지입니다. Meshy는 하위 호환성을 위해 이 값을 유지합니다.
Name
alpha_thumbnail_url
Type
string
Description
배경이 투명한(RGBA) thumbnail_url 버전의 다운로드 URL입니다. alpha_thumbnail: true로 작업을 생성하고 Meshy가 투명 미리보기를 렌더링한 경우에만 존재합니다.
Name
thumbnail_urls
Type
object
Description
4방향에서 본 3D 모델 미리보기의 다운로드 URL입니다. 각 값은 thumbnail_url과 동일한 재질 및 조명으로 렌더링된 512×512 PNG에 대한 서명된 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_url
Type
string
Description
텍스처를 유도한 이미지의 다운로드 URL입니다.
Name
ultra_mode
Type
boolean
⚠ 사용 중단
Description
대신 geometry_resolution을 참조하세요.
Name
geometry_resolution
Type
string
Description
작업이 실행된 Ultra 등급으로, 2k 또는 4k입니다. standard 작업에는 이 필드가 포함되지 않습니다.
Name
progress
Type
integer
Description
작업이 완료된 정도를 백분율로 나타냅니다. 작업이 시작되기 전에는 0이며, 성공하면 100입니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시간으로, 유닉스 밀리초 단위입니다. 작업이 시작되기 전에는 0입니다.
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
작업이 생성한 텍스처 맵으로, 객체 배열 형태입니다. 보통 다음 필드를 가진 객체 하나를 담고 있습니다:
- 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입니다. Meshy는 다음 조건을 모두 충족하여 작업을 생성한 경우에만 이 항목을 포함합니다:
  
  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일 때 존재합니다. FAILED 작업의 경우 Meshy가 작업 실패 시 크레딧을 환불하므로 0입니다.