텍스트로 3D API

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

텍스트로 3D는 2단계 워크플로를 사용합니다. 먼저 preview 작업(mode: "preview")을 생성하여 텍스처가 없는 3D 메시를 생성함으로써 형태를 평가할 수 있습니다. 그런 다음 완료된 preview 작업의 작업 ID를 refine 작업(mode: "refine")에 전달하여 메시에 텍스처를 적용합니다. 두 단계 모두 동일한 엔드포인트를 공유합니다.

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

텍스트로 3D Preview 작업 생성하기

이 엔드포인트는 텍스트 prompt로부터 텍스처가 없는 3D 메시(지오메트리만)를 생성하는 텍스트로 3D preview 작업을 생성합니다. 이는 2단계 워크플로우 중 첫 번째 단계입니다. preview가 성공하면, 반환된 작업 ID를 사용해 텍스처링을 위한 refine 작업을 생성하세요. 전체 응답 스키마는 텍스트로 3D 작업 객체를 참고하세요.

작업은 백그라운드에서 실행됩니다. 일반적으로 소요되는 시간은 처리 시간을 참고하세요.

파라미터

Name
mode
Type
string
필수
Description
preview 작업을 생성할 때 이 필드는 "preview"로 설정해야 합니다.
Name
prompt
Type
string
필수
Description
생성할 3D 모델이 어떤 종류의 객체인지 설명합니다. 최대 800자입니다.
Name
model_type
Type
string
기본값 standard
Description
3D 메시 생성 유형을 지정합니다.
사용 가능한 값:
- standard: 일반적인 고해상도 3D 메시 생성.
- smart-topology: ai_model(meshy-t2 또는 meshy-t2.5)과 함께 Smart Topology 모델을 선택합니다.
- lowpoly(지원 중단 예정, 2026년 10월 30일 지원 종료): 더 깔끔한 폴리곤에 최적화된 로우폴리 메시를 생성합니다. 대신 Meshy T2.5를 권장합니다: meshy-t2.5와 함께 사용하는 smart-topology.
smart-topology를 선택하면 should_remesh와 decimation_mode는 무시되며, topology: triangle만 허용됩니다.
lowpoly는 2026년 10월 30일에 지원이 종료됩니다. 해당 날짜 이후에는 model_type: "lowpoly"로 요청하면 오류가 반환됩니다. Meshy T2.5(ai_model: "meshy-t2.5"와 함께 사용하는 model_type: "smart-topology")로 전환하는 것을 권장합니다. lowpoly를 선택하면 ai_model, topology, target_polycount, should_remesh는 무시됩니다.
Name
ai_model
Type
string
기본값 latest
Description
사용할 모델의 ID입니다. 사용 가능한 값은 model_type에 따라 달라집니다.
Standard 생성 (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest(Meshy 7.1)
- meshy-7(지원 중단): 대신 meshy-7.1을 사용하세요.
Smart Topology 생성 (model_type: smart-topology):
- meshy-t2: Smart Topology 모델 — 더 깔끔한 topology, 자연스럽게 분리된 부위, 삼각형 출력, 그리고 target_polycount로 설정 가능한 면 수를 제공합니다.
- meshy-t2.5(기본값): 게임 asset을 위한 더 선명한 디테일. 삼각형 출력, 그리고 target_polycount로 설정 가능한 면 수를 제공합니다.
Name
geometry_resolution
Type
string
기본값 standard
Description
지오메트리 생성 패스입니다. 2k는 2048³ 해상도의 Ultra 패스를 실행하며, 4k는 가장 정밀한 표면 디테일을 위해 4096³ 해상도로 실행합니다.
사용 가능한 값: standard, 2k, 4k
preview mode에서만 지원됩니다. meshy-7.1 또는 latest가 필요합니다.
Name
ultra_mode
Type
boolean
⚠ 사용 중단
기본값 false
Description
대신 geometry_resolution을 사용하세요. ultra_mode: true는 geometry_resolution: "2k"와 동일합니다.
Name
should_remesh
Type
boolean
기본값 false (Meshy 6 and Meshy 7 models), true (others)
Description
리메시 단계를 활성화할지 여부를 제어합니다. 최고 품질의 모델을 위해서는 should_remesh를 false로 설정하는 것을 권장합니다.

다음 경우에만 적용 should_remesh = true

Name
topology
Type
string
기본값 triangle
Description
생성된 모델의 topology를 지정합니다.
사용 가능한 값:
- quad: 쿼드 중심 메시를 생성합니다.
- triangle: 감소된 삼각형 메시를 생성합니다.
Smart Topology 출력은 삼각형 전용입니다. ai_model meshy-t2 또는 meshy-t2.5와 함께 quad를 요청하면 오류가 반환됩니다.
Name
decimation_mode
Type
integer
Description
폴리곤 수 레벨을 설정하여 적응형 decimation을 활성화합니다. 설정 시 target_polycount는 무시됩니다.
사용 가능한 값:
- 1: 적응형 — 초고 폴리곤 수.
- 2: 적응형 — 고 폴리곤 수.
- 3: 적응형 — 중간 폴리곤 수.
- 4: 적응형 — 저 폴리곤 수.

Name
target_polycount
Type
integer
Description
출력물에서 목표로 하는 폴리곤(면) 수입니다. 실제 수치는 지오메트리에 따라 목표와 차이가 있을 수 있습니다.
target_polycount는 두 가지 독립적인 경우에 적용됩니다:
- 리메시 — standard 모델에서 should_remesh: true일 때. 메시는 대략 이 수치로 리메시(decimation)됩니다. 범위는 100에서 300,000이며, 기본값은 30,000입니다. decimation_mode가 설정되어 있으면 이것이 우선시되어 target_polycount는 무시됩니다.
- Smart Topology — model_type: smart-topology이고 ai_model이 meshy-t2 또는 meshy-t2.5일 때. 모델은 이 면 수로 직접 생성되며, 리메시는 실행되지 않고 should_remesh는 필요하지 않습니다. meshy-t2의 경우: 범위 100에서 15,000, 기본값 4,000. meshy-t2.5의 경우: 범위 100에서 30,000, 기본값 15,000.

Name
symmetry_mode
Type
string
⚠ 사용 중단
기본값 auto
Description
지원 중단됨. 이 파라미터는 더 이상 출력에 영향을 주지 않습니다.
symmetry_mode 필드는 모델 생성 과정에서 대칭 동작을 제어합니다.
유효한 값은 다음과 같습니다:
- off: 대칭을 비활성화합니다.
- auto: 입력 지오메트리를 기반으로 대칭을 자동으로 판단하고 적용합니다.
- on: 생성 중 대칭을 강제로 적용합니다.
Name
pose_mode
Type
string
기본값 ""
Description
생성된 모델의 포즈 mode를 지정합니다.
사용 가능한 값:
- 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 스타일은 자체적인 PBR 맵 세트를 생성하므로, Sculpture 스타일을 사용할 때는 enable_pbr을 false로 설정해야 합니다.
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로 설정하면, 작업은 preview의 투명 배경(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가 너무 긺: prompt가 문자 수 제한을 초과했습니다.
- low poly에서 지원되지 않는 모델: ai_model: "meshy-6-lite"는 model_type: "lowpoly"를 지원하지 않습니다.
- Ultra에서 지원되지 않는 모델: geometry_resolution에는 meshy-7.1 또는 latest가 필요합니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인해주세요.
Name
402 - Payment Required
Description
이 작업을 수행하기에 크레딧이 부족합니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
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"
}'

# Preview with Ultra 4K geometry, remesh and 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",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "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

Text to 3D Refine 작업 생성

이 엔드포인트는 Text to 3D refine 작업을 생성하며, 완료된 preview 메시에 텍스처를 적용합니다. 성공한 preview 작업에서 받은 preview_task_id를 제공해야 합니다. 이는 2단계 워크플로우 중 두 번째 단계입니다.

작업은 백그라운드에서 실행됩니다. 일반적으로 소요되는 시간은 처리 시간을 참조하세요.

파라미터

Name
mode
Type
string
필수
Description
refine 작업을 생성할 때는 이 필드를 "refine"으로 설정해야 합니다.
Name
preview_task_id
Type
string
필수
Description
해당 preview 작업의 id입니다.
지정한 preview 작업의 상태는 반드시 SUCCEEDED여야 합니다.
Name
enable_pbr
Type
boolean
기본값 false
Description
기본 색상 외에 PBR 맵(metallic, roughness, normal)을 생성합니다. ai_model이 meshy-6인 경우에는 emission 맵도 포함되지만, texture_resolution: 8k에서는 포함되지 않습니다(emission 맵이 생성되지 않음). meshy-6-lite, meshy-7.1, latest는 emission 맵을 생성하지 않으며, ai_model을 설정하지 않은 meshy-t2 preview의 refine 역시 마찬가지입니다.
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.1, 또는 latest여야 합니다. 8k에서는 emission 맵이 생성되지 않습니다.
Name
hd_texture
Type
boolean
⚠ 사용 중단
기본값 false
Description
대신 texture_resolution을 사용하세요 — texture_resolution: "4k"와 동일합니다. 두 값이 모두 설정된 경우 texture_resolution이 우선 적용됩니다.
Name
texture_prompt
Type
string
Description
텍스처링 과정을 안내할 추가 텍스트 prompt를 제공합니다. 최대 800자입니다.
Name
texture_image_url
Type
string
Description
텍스처링 과정을 안내할 2D 이미지를 제공합니다. 현재 .jpg, .jpeg, .png, .webp 형식을 지원합니다.
최대 파일 크기: 20MB.
이미지를 제공하는 방법은 두 가지입니다:
- 공개적으로 접근 가능한 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
기본값 inherited from the preview task
Description
refine에 사용할 모델의 ID입니다.
사용 가능한 값:
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (지원 중단): 대신 meshy-7.1을 사용하세요.
이 파라미터를 생략하면 preview 작업에서 사용된 모델을 그대로 상속하여, preview와 그 refine이 처음부터 끝까지 동일한 모델을 사용하게 됩니다. 이 상속을 재정의하려면 명시적인 값을 전달하세요.
명시적으로 latest를 지정하면 preview 작업에서와 정확히 동일하게 해석되므로(현재는 Meshy 7.1), latest preview와 그 latest refine은 항상 동일한 텍스처 모델로 귀결됩니다.
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.1과 latest는 이 값을 받아들이지만 무시하며, ai_model을 설정하지 않은 meshy-t2 preview의 refine도 마찬가지입니다. meshy-6-lite에서 이 값을 설정하면 오류가 반환됩니다.
Name
target_formats
Type
string[]
Description
출력에 포함할 3D 파일 형식을 지정합니다. 요청된 형식만 생성되어 반환되므로 작업 완료 시간을 줄일 수 있습니다. 생략하면 지원되는 모든 형식이 포함됩니다.
사용 가능한 값: glb, obj, fbx, stl, usdz, 3mf
생략하면 3mf를 제외한 모든 형식이 생성됩니다. 3mf는 명시적으로 지정한 경우에만 포함됩니다.
Name
alpha_thumbnail
Type
boolean
기본값 false
Description
true로 설정하면 작업은 추가로 투명 배경(RGBA) 버전의 preview를 렌더링하여 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 속성에는 새로 생성된 Text to 3D 작업의 id가 포함됩니다.

실패 모드

Name
400 - Bad Request
Description
요청이 허용되지 않았습니다. 일반적인 원인:
- 잘못된 작업 ID: preview_task_id가 유효하지 않거나 존재하지 않습니다.
- 작업 준비 미완료: preview 작업이 아직 성공하지 않았습니다.
- 모델 불일치: preview 작업의 AI 모델이 요청된 refine 모델과 호환되지 않습니다.
- remove_lighting에 지원되지 않는 모델: ai_model: "meshy-6-lite"와 함께 remove_lighting이 설정되었습니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인해 주세요.
Name
402 - Payment Required
Description
이 작업을 수행하기에 크레딧이 부족합니다.
Name
404 - Not Found
Description
preview_task_id로 지정한 preview 작업을 찾을 수 없습니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
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
}'

# Refine with auto-size and GLB format
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 작업 객체를 참조하세요.

이 엔드포인트는 preview 작업과 refine 작업 모두에 사용할 수 있습니다.

매개변수

Name
id
Type
path
Description
조회할 텍스트로 3D 작업의 고유 식별자입니다.

반환값

응답에는 텍스트로 3D 작업 객체가 포함됩니다. 자세한 내용은 텍스트로 3D 작업 객체 섹션을 확인하세요.

예시

Mode	샘플 모델
Preview
Refine

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입니다.

작업 상태

아직 PENDING 상태인 작업은 삭제되며 생성 시 소비된 크레딧이 환불됩니다.

이미 IN_PROGRESS 상태인 작업은 삭제할 수 없습니다. 요청은 409 Conflict로 거부되며 작업은 계속 실행됩니다. 워커가 이미 시작한 작업에 대한 크레딧은 환불되지 않으므로, 실행 중에 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. SUCCEEDED, FAILED 또는 CANCELED 상태에 도달할 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED 또는 CANCELED)에 있는 작업은 환불 없이 삭제됩니다.

반환값

성공 시 200 OK를 반환하며, 작업이 IN_PROGRESS일 때는 409 Conflict를 반환합니다.

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 on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left 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."
}

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

Text to 3D 작업 목록 조회

이 엔드포인트를 사용하면 Text to 3D 작업 목록을 조회할 수 있습니다.

매개변수

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

반환 값

Text to 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 작업 스트리밍하기

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

매개변수

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

반환 값

텍스트로 3D 작업 객체의 스트림을 Server-Sent Events 형태로 반환합니다.

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

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

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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 작업 객체는 텍스트 입력으로부터 3D 모델을 생성하기 위해 Meshy가 추적하는 작업 단위입니다. 텍스트로 3D API에는 preview와 refine이라는 두 가지 단계가 있습니다. preview 단계는 메시만 있는 3D 모델을 생성하는 단계이며, refine 단계는 preview 단계 결과를 기반으로 텍스처가 적용된 3D 모델을 생성하는 단계입니다.

이 객체는 다음과 같은 속성을 가집니다:

속성

Name
id
Type
string
Description
작업의 고유 식별자입니다. 구현 세부 사항으로서 작업 id에 k-정렬 가능한 UUID를 사용하지만, id의 형식에 대해 어떠한 가정도 하지 않아야 합니다.
Name
type
Type
string
Description
텍스트로 3D 작업의 유형입니다. 가능한 값은 preview 단계 작업의 경우 text-to-3d-preview, refine 단계 작업의 경우 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입니다. target_formats를 통해 3mf가 요청된 경우에만 존재합니다.
Name
prompt
Type
string
Description
작업을 생성할 때 사용된 수정되지 않은 prompt입니다.
Name
negative_prompt
Type
string
⚠ 사용 중단
Description
이전 버전과의 호환성을 위해 유지됩니다. 이 필드는 생성된 모델에 기능적인 영향을 주지 않습니다.
Name
art_style
Type
string
⚠ 사용 중단
Description
preview 작업을 생성할 때 사용된 수정되지 않은 art_style입니다. Meshy-6에서는 지원되지 않습니다.
Name
texture_richness
Type
string
⚠ 사용 중단
Description
이전 버전과의 호환성을 위해 유지됩니다. 이 필드는 생성된 모델에 기능적인 영향을 주지 않습니다.
Name
texture_prompt
Type
string
Description
refine 단계에서 텍스처링 프로세스를 안내하기 위해 제공되는 추가 텍스트 prompt입니다.
Name
ultra_mode
Type
boolean
⚠ 사용 중단
Description
지원 중단됨; 대신 geometry_resolution을 참조하세요.
Name
geometry_resolution
Type
string
Description
preview 작업이 실행된 Ultra 등급(2k 또는 4k)입니다. standard인 경우 생략됩니다.
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입니다.
타임스탬프는 RFC 3339 표준에 따라 1970년 1월 1일 UTC로부터 경과한 밀리초 수를 나타냅니다. 예를 들어, 2023년 9월 1일 금요일 오후 12시 00분 00초 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
  base color 맵 이미지를 다운로드할 수 있는 URL입니다.
- Name
  metallic
  Type
  string
  Description
  metallic 맵 이미지를 다운로드할 수 있는 URL입니다.
  작업이 enable_pbr: false로 생성된 경우, 이 속성은 생략됩니다.
- Name
  normal
  Type
  string
  Description
  노멀 맵 이미지를 다운로드할 수 있는 URL입니다.
  작업이 enable_pbr: false로 생성된 경우, 이 속성은 생략됩니다.
- Name
  roughness
  Type
  string
  Description
  roughness 맵 이미지를 다운로드할 수 있는 URL입니다.
  작업이 enable_pbr: false로 생성된 경우, 이 속성은 생략됩니다.
- Name
  emission
  Type
  string
  Description
  emission 맵 이미지를 다운로드할 수 있는 URL입니다.
  작업이 enable_pbr: false로 생성된 경우, ai_model이 meshy-6-lite, meshy-7.1, 또는 latest인 경우, 또는 작업이 ai_model을 설정하지 않고 meshy-t2 preview를 refine하는 경우, 이 속성은 생략됩니다.
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
}