이미지로 3D API

이미지로 3D API는 Meshy의 이미지로 3D 기능을 귀하의 애플리케이션에 통합할 수 있는 기능입니다. 이 섹션에서는 이 API를 시작하는 데 필요한 모든 정보를 찾을 수 있습니다.

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

이미지로 3D 작업 생성

이 endpoint를 통해 새로운 이미지로 3D 작업을 생성할 수 있습니다. Image to 3D 작업 객체에 포함된 속성은 The Image to 3D Task Object를 참조하세요.

파라미터

input_task_id 또는 image_url 중 하나만 필수입니다. 두 가지 모두 제공된 경우, input_task_id가 우선합니다.

Name
input_task_id
Type
string
필수
Description
출력이 입력 이미지로 사용되어야 하는 완료된 이미지 생성 작업의 ID. 이 작업은 다음 작업 중 하나이어야 합니다: 텍스트로 이미지 또는 이미지로 이미지. 또한, API를 통해 실행되었어야 하며, 상태가 SUCCEEDED이어야 하고 정확히 하나의 이미지를 생성해야 합니다.

Name
image_url
Type
string
필수
Description
Meshy가 모델 생성에 사용할 이미지를 제공하십시오. 우리는 현재 .jpg, .jpeg 및 .png 형식을 지원합니다. 이미지를 제공하는 두 가지 방법이 있습니다:
- 공개적으로 접근 가능한 URL: 공용 인터넷에서 접근 가능한 URL.
- Data URI: 이미지의 base64-로 인코딩된 Data URI. Data URI 예제: data:image/jpeg;base64,<your base64-encoded image data>.

Name
model_type
Type
string
기본값 standard
Description
3D 메시 생성의 유형을 지정합니다.
사용 가능한 값:
- standard: 일반 고화질 3D 메시 생성.
- smart-topology: ai_model (meshy-t1 또는 meshy-t2)로 Smart Topology 모델을 선택합니다.
- lowpoly (지원 중단): 클리너 폴리곤으로 최적화된 로우폴리 메시를 생성합니다. 대신 smart-topology를 사용하는 것을 권장합니다.
smart-topology가 선택된 경우, topology, should_remesh, 및 save_pre_remeshed_model은 무시됩니다.
lowpoly가 선택된 경우, ai_model, topology, target_polycount, should_remesh 및 save_pre_remeshed_model은 무시됩니다.
Name
ai_model
Type
string
기본값 latest
Description
사용할 모델의 ID입니다. 사용 가능한 값은 model_type에 따라 다릅니다.
표준 생성 (model_type: standard):
- meshy-5, meshy-6, meshy-7, latest (Meshy 7)
Smart Topology 생성 (model_type: smart-topology):
- meshy-t2 (기본값, 권장): Smart Topology 모델 — 클리너 topology, 본래 분리된 부품, 삼각형 출력, target_polycount로 설정할 수 있는 면 개수를 특징으로합니다.
- meshy-t1: 이전의 로우폴리 모델; target_polycount로 설정할 수 있는 면 개수를 지원하지 않습니다.
Name
ultra_mode
Type
boolean
기본값 false
Description
더 높은 충실도의 지오메트리와 더 세밀한 표면 디테일을 위한 Ultra 생성을 활성화합니다.
ai_model이 meshy-7(또는 latest)인 경우에만 지원됩니다.
Name
should_texture
Type
boolean
기본값 true
Description
텍스처가 생성될지 여부를 결정합니다. false로 설정하면 텍스처 없이 메시가 제공됩니다.

다음 경우에만 적용 should_texture = true

Name
enable_pbr
Type
boolean
기본값 false
Description
기본 색상 외에 PBR 맵 (메탈, 러프니스, 노멀)을 생성합니다. ai_model이 meshy-6일 때 방출 맵도 포함됩니다. 단, 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-5로 사용할 수 없습니다. 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를 사용하여 모델을 텍스처링합니다. 텍스트 또는 이미지를 통해 텍스처링하면 작업당 10 크레딧이 소모됩니다.

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

다음 경우에만 적용 should_remesh = true

Name
topology
Type
string
기본값 triangle
Description
생성된 모델의 topology를 지정합니다.
사용 가능한 값:
- quad: 쿼드 우세 메시 생성.
- triangle: 감산된 삼각형 메시 생성.
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
target_polycount
Type
integer
Description
출력의 폴리곤(웅장)의 대상 수입니다. 실제 카운트는 지오메트리에 따라 대상과 다를 수 있습니다.
target_polycount는 두 가지 독립적인 경우에 적용됩니다:
- 리메시 — standard 모델의 should_remesh: true로 설정된 경우. 메시가 이 수량에 가깝도록 리메시(축소)됩니다. 범위 100~300,000, 기본값 30,000. decimation_mode가 설정된 경우, 우선권을 가지고 target_polycount는 무시됩니다.
- Smart Topology — model_type: smart-topology와 ai_model: meshy-t2을 사용하는 경우. 모델은 이 면 개수로 직접 생성됩니다. 리메시는 실행되지 않으며 should_remesh는 필요하지 않습니다. 범위 100~15,000, 기본값 4,000.

Name
symmetry_mode
Type
string
⚠ 사용 중단
기본값 auto
Description
지원 중단. 이 파라미터는 더 이상 출력에 영향을 주지 않습니다.
symmetry_mode 필드는 모델 생성 프로세스 중 대칭 동작을 제어합니다.
유효한 값은 다음과 같습니다:
- off: 대칭 비활성화.
- auto: 입력 지오메트리를 기반으로 대칭을 자동으로 결정하고 적용.
- on: 생성하는 동안 대칭 적용.
Name
pose_mode
Type
string
기본값 ""
Description
생성된 model의 포즈 모드를 지정합니다.
사용 가능한 값:
- 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인 경우에만 지원됩니다.
Name
moderation
Type
boolean
기본값 false
Description
true로 설정된 경우, 입력 콘텐츠는 자동으로 잠재적으로 해로운 콘텐츠에 대한 스크리닝이 진행됩니다. 해로운 콘텐츠가 감지되면 작업이 생성으로 진행되지 않습니다.
image_url, texture_image_url 및 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_url 또는 input_task_id 중 하나를 제공해야 합니다.
- 잘못된 입력 작업: input_task_id는 정확히 한 이미지의 텍스트로 이미지 또는 이미지로 이미지 작업이어야 하며, SUCCEEDED 상태여야 합니다.
- 잘못된 이미지 형식: 제공된 image_url이 지원되는 형식이 아닙니다(.jpg, .jpeg, .png).
- 접근 불가한 URL: image_url을 다운로드할 수 없습니다 (404 또는 timeout).
- 잘못된 Data URI: base64 문자열이 잘못되었습니다.
- 잘못된 파라미터 조합: enable_pbr은 should_texture가 true일 때만 지원됩니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인하세요.
Name
402 - Payment Required
Description
이 작업을 수행할 크레딧이 부족합니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

/openapi/v1/image-to-3d

# 필수 파라미터로 간단한 요청
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>"
  }'

# 리메시, PBR 및 A-포즈 사용
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>",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

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

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

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

이 endpoint를 통해 유효한 작업 id를 받은 이미지로 3D 작업을 가져올 수 있습니다. Image to 3D 작업 객체에 포함된 속성은 The Image to 3D Task Object를 참조하세요.

파라미터

Name
id
Type
path
Description
가져올 이미지로 3D 작업의 고유 식별자입니다.

반환값

응답은 Image to 3D 작업 객체를 포함합니다. 자세한 내용은 The Image to 3D Task Object 섹션을 참조하세요.

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": {
    "message": ""
  },
  "consumed_credits": 30
}

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

이미지로 3D 작업 삭제

이 endpoint는 이미지로 3D 작업을 영구히 삭제하며, 관련된 모든 모델과 데이터를 포함합니다. 이 작업은 되돌릴 수 없습니다.

경로 파라미터

Name
id
Type
path
Description
삭제할 이미지로 3D 작업의 ID입니다.

반환값

성공하면 200 OK를 반환합니다.

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를 반환합니다.

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

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

이 endpoint를 통해 이미지로 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: 생성 시간 내림차순으로 정렬.

반환값

페이지별로 The Image to 3D Task Objects을 나열하여 반환합니다.

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": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

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

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

이 endpoint는 서버 전송 이벤트(SSE)를 사용하여 실시간 업데이트를 스트리밍합니다.

파라미터

Name
id
Type
path
Description
스트리밍할 이미지로 3D 작업의 고유 식별자입니다.

반환값

서버 전송 이벤트로 The Image to 3D Task Objects 스트림을 반환합니다.

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

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

// 오류 이벤트 예시
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": "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
}

The Image to 3D Task Object

이미지로 3D 작업 객체는 Meshy가 이미지 입력으로부터 3D 모델을 생성하기 위해 추적하는 작업 단위입니다. 이 객체는 다음 속성을 포함합니다:

속성

Name
id
Type
string
Description
작업의 고유 식별자입니다. 작업 ID에 대해 k-sortable UUID를 구현합니다.
Name
type
Type
string
Description
이미지로 3D 작업의 유형입니다. 값은 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
  텍스처가 제공될 때 OBJ 내보내기와 함께 반환되는 MTL 파일로 다운로드 가능한 URL.
- 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
texture_image_url
Type
string
Description
텍스처링 프로세스를 안내하는 데 사용된 텍스처 이미지의 다운로드 가능한 URL입니다.
Name
ultra_mode
Type
boolean
Description
작업이 생성될 때 사용된 ultra_mode 값을 그대로 반환합니다. ultra_mode를 명시적으로 설정한 meshy-7(또는 latest) 작업에만 존재하며, 그 외에는 생략됩니다.
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 PM 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, meshy-7, 또는 latest인 경우 이 속성이 생략됩니다.
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을 반환합니다 (실패 시 크레딧이 환불됩니다).

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": {
    "message": ""
  },
  "consumed_credits": 30
}