텍스트로 3D API

텍스트로 3D API는 자체 애플리케이션에 Meshy의 텍스트로 3D 기능을 통합할 수 있는 기능입니다. 이 섹션에서는 이 API를 시작하는 데 필요한 모든 정보를 제공합니다.

텍스트로 3D는 두 단계의 워크플로우를 사용합니다. 먼저, 텍스처 없이 3D 메시를 생성하여 모양을 평가할 수 있도록 미리보기 태스크(mode: "preview")를 만드세요. 그런 다음, 완료된 미리보기의 태스크 ID를 정제 태스크(mode: "refine")로 전달하여 메시에 텍스처를 적용하세요. 두 단계는 동일한 엔드포인트를 공유합니다.

POST/openapi/v2/text-to-3d

미리보기 태스크 만들기

이 엔드포인트는 텍스트 프롬프트로부터 텍스처가 없는 3D 메시(지오메트리만)를 생성하는 텍스트로 3D 미리보기 태스크를 생성합니다. 이는 두 단계 워크플로우의 첫 번째 단계입니다. 미리보기가 성공하면 반환된 태스크 ID를 사용하여 텍스처링을 위한 정제 태스크 만들기를 참조하세요. 전체 응답 스키마는 텍스트로 3D 태스크 객체를 참조하세요.

파라미터

Name
mode
Type
string
필수
Description
미리보기 태스크를 만들 때 이 필드는 "preview"로 설정해야 합니다.
Name
prompt
Type
string
필수
Description
3D 모델이 어떤 종류의 객체인지 설명하세요. 최대 600자.
Name
model_type
Type
string
기본값 standard
Description
3D 메시 생성 유형을 지정하세요.
사용 가능한 값:
- standard: 일반 높은 세부 수준의 3D 메시 생성.
- smart-topology: ai_model(meshy-t2)로 Smart Topology 모델 선택.
- lowpoly (지원 중단): 깨끗한 폴리곤으로 최적화된 로우폴리 메시 생성. 대신 smart-topology를 사용하는 것을 권장합니다.
smart-topology가 선택된 경우, should_remesh 및 decimation_mode는 무시되며, topology: triangle만 허용됩니다.
lowpoly가 선택된 경우, ai_model, topology, target_polycount, 및 should_remesh는 무시됩니다.
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로 설정할 수 있는 면 개수.
Name
ultra_mode
Type
boolean
기본값 false
Description
더 높은 충실도의 지오메트리와 더 세부적인 표면 세부 사항을 위한 울트라 모드를 활성화합니다. 생성이 더 오래 걸리며 크레딧이 5 증가합니다.
ai_model이 meshy-7(또는 latest)일 때, 그리고 preview mode에서만 지원됩니다.
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: 디시메이션된 삼각형 메시 생성.
Smart Topology 출력은 삼각형 전용입니다. ai_model: meshy-t2와 함께 quad를 요청하면 오류가 반환됩니다.
Name
decimation_mode
Type
integer
Description
폴리곤 수 수준을 설정하여 적응형 디시메이션을 활성화합니다. 설정되면, target_polycount는 무시됩니다.
사용 가능한 값:
- 1: 적응형 — 초고 폴리곤 수.
- 2: 적응형 — 높은 폴리곤 수.
- 3: 적응형 — 중간 폴리곤 수.
- 4: 적응형 — 낮은 폴리곤 수.

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
생성된 모델의 포즈 모드를 지정하세요.
사용 가능한 값:
- a-pose: A 포즈로 모델 생성.
- t-pose: T 포즈로 모델 생성.
- "" (빈 문자열): 특정 포즈 적용 안 함.
Name
is_a_t_pose
Type
boolean
⚠ 사용 중단
기본값 false
Description
대신 pose_mode를 사용하세요. 모델을 A/T 포즈로 생성할지 여부.
Name
art_style
Type
string
⚠ 사용 중단
기본값 realistic
Description
Meshy-6에서 지원되지 않음. Meshy-6을 사용하는 요청은 art_style을 무시하며, 일부 조합은 오류를 초래할 수 있음. 사용 가능한 값: realistic, sculpture.
Sculpture 스타일을 사용할 때 enable_pbr는 false로 설정해야 합니다. 이는 Sculpture 스타일이 자체 PBR 맵 세트를 생성하기 때문입니다.
Name
moderation
Type
boolean
기본값 false
Description
true로 설정되면, 입력 콘텐츠는 자동으로 잠재적인 유해 콘텐츠로부터 선별됩니다. 유해 콘텐츠가 감지되면, 태스크는 생성으로 진행되지 않습니다.
prompt의 텍스트가 선별됩니다.
Name
target_formats
Type
string[]
Description
출력에 포함할 3D 파일 형식을 지정합니다. 요청한 형식만 생성 및 반환되어 태스크 완료 시간을 줄일 수 있습니다. 생략하면, 모든 지원 형식이 포함됩니다.
사용 가능한 값: glb, obj, fbx, stl, usdz, 3mf
생략된 경우, 3mf를 제외한 모든 형식이 생성됩니다. 3mf는 명시적으로 요청된 경우에만 포함됩니다.
Name
alpha_thumbnail
Type
boolean
기본값 false
Description
true로 설정되면, 태스크는 추가로 투명 배경(RGBA) 버전의 미리보기를 렌더링하고 GET 응답에 alpha_thumbnail_url로 반환합니다. 기존의 thumbnail_url 필드는 변경되지 않습니다.
Name
auto_size
Type
boolean
기본값 false
Description
true로 설정되면, 서비스는 AI 비전을 사용하여 객체의 실제 높이를 자동으로 추정하고 모델 크기를 조정합니다. origin_at가 명시적으로 설정되지 않았다면, bottom이 기본 원점 위치로 설정됩니다.

다음 경우에만 적용 auto_size = true

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

반환값

응답의 result 속성에는 새로 생성된 텍스트로 3D 태스크의 태스크 id가 포함되어 있습니다.

실패 모드

Name
400 - Bad Request
Description
요청이 부적합했습니다. 일반적인 원인:
- 누락된 파라미터: 필수 파라미터(예: prompt, mode)가 누락되었습니다.
- 잘못된 파라미터: art_style이 허용된 값이 아닙니다.
- 프롬프트가 너무 긺: prompt가 문자 제한을 초과했습니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인하세요.
Name
402 - Payment Required
Description
이 작업을 수행하기에 충분한 크레딧이 없습니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

/openapi/v2/text-to-3d

# 필수 파라미터만으로 간단한 미리보기
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# 리메시 및 A-pose가 포함된 미리보기
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

POST/openapi/v2/text-to-3d

텍스트로 3D 정제 태스크 만들기

이 엔드포인트는 완료된 미리보기 메시에 텍스처를 적용하는 텍스트로 3D 정제 태스크를 생성합니다. 성공한 미리보기 태스크에서 preview_task_id를 제공해야 합니다. 이는 두 단계 워크플로우의 두 번째 단계입니다.

파라미터

Name
mode
Type
string
필수
Description
정제 태스크를 만들 때 이 필드는 "refine"으로 설정되어야 합니다.
Name
preview_task_id
Type
string
필수
Description
해당 미리보기 태스크 id입니다.
주어진 미리보기 태스크의 상태는 SUCCEEDED여야 합니다.
Name
enable_pbr
Type
boolean
기본값 false
Description
기본 색상 외에도 금속성, 거칠기, 노멀의 PBR 맵을 생성합니다. texture_resolution: 8k에서는 방출 맵은 생성되지 않지만, ai_model이 meshy-6인 경우 방출 맵도 포함됩니다. meshy-7(및 latest)은 방출 맵을 생성하지 않습니다.
Name
texture_resolution
Type
string
기본값 2k
Description
기본 색상 텍스처 해상도. 2k (2048×2048), 4k (4096×4096), 8k (8192×8192). 더 높은 해상도는 더 많은 표면 세부 사항을 캡처합니다. refine mode에만 적용됩니다.
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>
원본 asset과 업로드된 이미지 간에 상당한 지오메트리 차이가 있는 경우 이미지 텍
스처링이 최적으로 작동하지 않을 수 있습니다. texture_image_url이나 texture_prompt 중 하나만 텍스처링 프로세스를 안내하는 데 사용할 수 있습니다. 둘 다 제공된 경우, 기본적으로 texture_prompt가 모델을 텍스처링하는 데 사용됩니다.
Name
ai_model
Type
string
기본값 latest
Description
정제를 위해 사용할 모델의 ID입니다. 사용 가능한 값: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
latest는 미리보기 태스크에서 정확히 작동되므로 latest 미리보기와 그 latest 정제는 항상 동일한 텍스처 모델에 적용됩니다.
Name
moderation
Type
boolean
기본값 false
Description
true로 설정되면, 입력 콘텐츠는 자동으로 잠재적인 유해 콘텐츠로부터 선별됩니다. 유해 콘텐츠가 감지되면, 태스크는 생성으로 진행되지 않습니다.
texture_prompt에서의 텍스트와 texture_image_url에서의 이미지가 선별됩니다.
Name
remove_lighting
Type
boolean
기본값 true
Description
기본 색상 텍스처에서 하이라이트 및 그림자를 제거하여 사용자 정의 조명 설정 하에서 더 나은 결과를 생성합니다.
ai_model이 meshy-6일 때만 효과가 있습니다. meshy-7(및 latest)에서는 이 파라미터가 수락되지만 무시됩니다.
Name
target_formats
Type
string[]
Description
출력에 포함할 3D 파일 형식을 지정합니다. 요청한 형식만 생성 및 반환되어 태스크 완료 시간을 줄일 수 있습니다. 생략하면, 모든 지원 형식이 포함됩니다.
사용 가능한 값: glb, obj, fbx, stl, usdz, 3mf
생략된 경우, 3mf를 제외한 모든 형식이 생성됩니다. 3mf는 명시적으로 요청된 경우에만 포함됩니다.
Name
alpha_thumbnail
Type
boolean
기본값 false
Description
true로 설정되면, 태스크는 추가로 투명 배경(RGBA) 버전의 미리보기를 렌더링하고 GET 응답에 alpha_thumbnail_url로 반환합니다. 기존의 thumbnail_url 필드는 변경되지 않습니다.
Name
auto_size
Type
boolean
기본값 false
Description
true로 설정되면, 서비스는 AI 비전을 사용하여 객체의 실제 높이를 자동으로 추정하고 모델 크기를 조정합니다. origin_at가 명시적으로 설정되지 않았다면, bottom이 기본 원점 위치로 설정됩니다.

다음 경우에만 적용 auto_size = true

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

반환값

응답의 result 속성에는 새로 생성된 텍스트로 3D 태스크의 태스크 id가 포함되어 있습니다.

실패 모드

Name
400 - Bad Request
Description
요청이 부적합했습니다. 일반적인 원인:
- 잘못된 태스크 ID: preview_task_id가 잘못되었거나 존재하지 않습니다.
- 태스크 준비 안 됨: 미리보기 태스크가 아직 성공하지 않았습니다.
- 모델 불일치: 미리보기 태스크의 AI 모델이 요청된 정제 모델과 호환되지 않습니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인하세요.
Name
402 - Payment Required
Description
이 작업을 수행하기에 충분한 크레딧이 없습니다.
Name
404 - Not Found
Description
preview_task_id로 지정된 미리보기 태스크를 찾을 수 없었습니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

/openapi/v2/text-to-3d

# 기본 정제 태스크
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# 자동 크기 조정 및 GLB 형식이 포함된 정제 태스크
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

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

GET/openapi/v2/text-to-3d/:id

텍스트로 3D 태스크 가져오기

이 엔드포인트를 통해 유효한 태스크 id를 가진 텍스트로 3D 태스크를 가져올 수 있습니다. 텍스트로 3D 태스크 객체를 참조하여 텍스트로 3D 태스크 객체에 포함된 속성을 확인하세요.

이 엔드포인트는 미리보기와 정제 태스크 모두에 사용할 수 있습니다.

파라미터

Name
id
Type
path
Description
검색할 텍스트로 3D 태스크의 고유 식별자입니다.

반환값

응답에는 텍스트로 3D 태스크 객체가 포함되어 있습니다. 텍스트로 3D 태스크 객체 섹션을 참조하여 세부 사항을 확인하세요.

예시

모드	샘플 모델
미리보기
정제

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}

DELETE/openapi/v2/text-to-3d/:id

텍스트로 3D 태스크 삭제

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

경로 파라미터

Name
id
Type
path
Description
삭제할 텍스트로 3D 태스크의 ID입니다.

반환값

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

Request

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

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

GET/openapi/v2/text-to-3d

텍스트로 3D 태스크 목록

이 엔드포인트를 통해 텍스트로 3D 태스크 목록을 가져올 수 있습니다.

파라미터

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

반환값

페이지네이션된 텍스트로 3D 태스크 객체 목록을 반환합니다.

Request

GET

/openapi/v2/text-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

GET/openapi/v2/text-to-3d/:id/stream

텍스트로 3D 태스크 스트리밍

이 엔드포인트는 서버-전송 이벤트(SSE)를 사용하여 텍스트로 3D 태스크의 실시간 업데이트를 스트리밍합니다.

파라미터

Name
id
Type
path
Description
스트리밍할 텍스트로 3D 태스크의 고유 식별자입니다.

반환값

서버-전송 이벤트로 텍스트로 3D 태스크 객체의 스트림을 반환합니다.

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

Request

GET

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

curl -N https://api.meshy.ai/openapi/v2/text-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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": 20
}

텍스트로 3D 태스크 객체

텍스트로 3D 태스크 객체는 Meshy가 텍스트 입력을 통해 3D 모델을 생성하기 위해 추적하는 작업 단위입니다. 텍스트로 3D API에는 미리보기와 정제라는 두 가지 단계가 있습니다. 미리보기 단계는 메시 전용 3D 모델을 생성하고, 정제 단계는 미리보기 단계의 결과를 기반으로 텍스처 3D 모델을 생성합니다.

객체에는 다음과 같은 속성이 있습니다:

속성

Name
id
Type
string
Description
태스크의 고유 식별자입니다. 구현 세부 사항으로서 k-sortable UUID를 태스크 ID로 사용하지만, ID 형식에 대한 가정을 해서는 안됩니다.
Name
type
Type
string
Description
텍스트로 3D 태스크의 유형입니다. 미리보기 단계 태스크의 경우 text-to-3d-preview이고, 정제 단계 태스크의 경우 text-to-3d-refine입니다.
Name
model_urls
Type
object
Description
Meshy에 의해 생성된 텍스처 3D 모델 파일의 다운로드 가능한 URL입니다. 형식이 생성되지 않은 경우 빈 문자열 대신 해당 형식은 생략됩니다.
- Name
  glb
  Type
  string
  Description
  GLB 파일의 다운로드 가능한 URL.
- Name
  fbx
  Type
  string
  Description
  FBX 파일의 다운로드 가능한 URL.
- Name
  usdz
  Type
  string
  Description
  USDZ 파일의 다운로드 가능한 URL.
- Name
  obj
  Type
  string
  Description
  OBJ 파일의 다운로드 가능한 URL.
- Name
  mtl
  Type
  string
  Description
  MTL 파일의 다운로드 가능한 URL.
- Name
  stl
  Type
  string
  Description
  STL 파일의 다운로드 가능한 URL.
- Name
  3mf
  Type
  string
  Description
  3MF 파일의 다운로드 가능한 URL. 3mf가 target_formats를 통해 요청된 경우에만 존재합니다.
Name
prompt
Type
string
Description
태스크를 생성할 때 사용된 원본 prompt입니다.
Name
negative_prompt
Type
string
⚠ 사용 중단
Description
하위 호환성을 위해 유지됩니다. 이 필드는 생성된 모델에 기능적 영향을 미치지 않습니다.
Name
art_style
Type
string
⚠ 사용 중단
Description
미리보기 태스크를 생성할 때 사용된 원본 art_style입니다. Meshy-6에서 지원되지 않습니다.
Name
texture_richness
Type
string
⚠ 사용 중단
Description
하위 호환성을 위해 유지됩니다. 이 필드는 생성된 모델에 기능적 영향을 미치지 않습니다.
Name
texture_prompt
Type
string
Description
정제 단계에서 텍스처링 프로세스를 안내하기 위해 제공된 추가 텍스트 프롬프트입니다.
Name
ultra_mode
Type
boolean
Description
미리보기 태스크가 생성된 ultra_mode 값을 반영합니다. 명시적으로 ultra_mode를 설정한 meshy-7(또는 latest) 미리보기 태스크에만 존재합니다; 그렇지 않으면 생략됩니다.
Name
texture_image_url
Type
string
Description
텍스처링 프로세스를 안내하기 위해 사용된 텍스처 이미지의 다운로드 가능한 URL입니다.
Name
thumbnail_url
Type
string
Description
모델 파일의 썸네일 이미지의 다운로드 가능한 URL입니다.
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url의 투명 배경(RGBA) 버전의 다운로드 가능한 URL입니다. 태스크가 alpha_thumbnail: true로 생성되고, 투명 프리뷰가 성공적으로 렌더링된 경우에만 존재합니다; 그렇지 않으면 이 필드는 생략됩니다.
Name
video_url
Type
string
⚠ 사용 중단
Description
미리보기 비디오의 다운로드 가능한 URL입니다. 향후 릴리스에서 제거될 예정입니다.
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
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을 반환합니다(실패 시 크레딧이 환불됨).

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}