텍스트로 3D API

2단계 워크플로의 단계입니다. preview 태스크를 생성하려면 preview를 전송하세요.

생성할 객체를 설명하는 텍스트로, 최대 800자입니다. 더 긴 텍스트를 보내면 400이 반환됩니다.

생성할 3D 메시의 유형입니다.

사용 가능한 값:

• standard: 고해상도 3D 메시
• smart-topology: Smart Topology 메시입니다. ai_model(meshy-t2 또는 meshy-t2.5)로 모델을 선택합니다.

smart-topology를 사용하면 Meshy는 should_remesh와 decimation_mode를 무시하며, topology: triangle만 허용합니다.

3D 모델을 생성하는 AI 모델입니다. 사용 가능한 값은 model_type에 따라 다릅니다.

표준 모델 (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: 더 깔끔한 topology, 기본적으로 분리된 파츠, triangle 출력, target_polycount로 설정하는 면 개수
• meshy-t2.5 (기본값): 게임 에셋에 적합한 더 선명한 디테일, triangle 출력, target_polycount로 설정하는 면 개수

지오메트리 생성 패스입니다. preview 태스크에만 적용됩니다. refine에서 이 파라미터를 사용하면 400이 반환됩니다.

사용 가능한 값:

• standard
• 2k: 2048³에서 Ultra 패스를 실행
• 4k: 더 정교한 표면 디테일을 위해 4096³에서 Ultra 패스를 실행

2k는 meshy-7.1, latest, 또는 지원 중단된 meshy-7이 필요합니다. 4k는 meshy-7.1 또는 latest가 필요합니다. 다른 모델은 400을 반환합니다.

대신 geometry_resolution을 전송하세요. ultra_mode: true는 geometry_resolution: "2k"와 동일합니다.

생성 후 모델을 리메시할지 여부입니다. 최고 품질의 3D 모델을 원하면 false를 전송하세요.

목표로 할 면의 개수입니다. 지오메트리에 따라 결과가 목표값과 다를 수 있습니다. 이는 두 가지 개별적인 경우에 적용됩니다:

• 리메시: 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는 필요하지 않습니다.

다음 표는 각 경우의 범위와 기본값을 보여줍니다:

범위를 벗어난 값은 400을 반환합니다.

생략하세요. 이 파라미터는 출력에 영향을 주지 않습니다.

사용 가능한 값:

• off: 대칭을 비활성화
• auto: 입력 지오메트리를 기반으로 대칭을 적용
• on: 생성 중 대칭을 강제 적용

생성된 모델의 포즈입니다.

사용 가능한 값:

• a-pose: A 포즈
• t-pose: T 포즈
• "" (빈 문자열): 특정 포즈 없음

대신 pose_mode를 전송하세요. 모델을 A 포즈 또는 T 포즈로 생성할지 여부입니다.

생략하세요. Meshy는 이를 무시합니다.

생성 전에 prompt에서 유해한 콘텐츠를 검사할지 여부입니다. Meshy가 유해한 콘텐츠를 감지하면 요청은 400을 반환하고 Meshy는 태스크를 생성하지 않습니다.

생성할 파일 형식입니다. Meshy는 이 형식들만 생성하고 반환하므로 태스크 시간이 단축될 수 있습니다. 생략하면 Meshy는 3mf를 제외한 모든 형식을 생성하며, 3mf는 요청할 때만 생성합니다.

사용 가능한 값:

• glb
• obj
• fbx
• stl
• usdz
• 3mf

투명 배경(RGBA)의 preview도 렌더링할지 여부이며, 태스크를 가져올 때 alpha_thumbnail_url로 반환됩니다. thumbnail_url은 변경되지 않습니다.

AI 비전을 사용해 객체의 실제 높이를 추정하고 모델을 그 크기로 조정할지 여부입니다. origin_at을 설정하지 않으면 Meshy는 원점을 바닥에 둡니다.

요청을 실행할 수 없습니다. 오류 메시지에서 어떤 문제가 발견되었는지 알려줍니다. 예를 들면:

• 파라미터 누락: prompt 또는 mode와 같은 필수 파라미터가 누락되었습니다.
• Prompt가 너무 긺: prompt가 문자 제한을 초과했습니다.
• Ultra에 지원되지 않는 모델: geometry_resolution이 2k 또는 4k인데, 이를 실행할 수 없는 ai_model을 사용했습니다.

요청을 수정한 후 다시 전송하세요. 오류를 참고하세요.

API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.

예를 들면:

• 크레딧 부족: 계정에 이 태스크를 수행할 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. 크레딧 잔액을 확인한 후 다시 시도하세요.
• 무료 플랜: 태스크를 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 후 다시 시도하세요.

콘텐츠 moderation이 prompt 또는 입력 이미지를 차단했습니다. 입력을 변경한 후 다시 시도하세요.

속도 제한을 초과했습니다. 잠시 기다린 후 다시 시도하세요. 속도 제한을 참고하세요.

2단계 워크플로우의 단계입니다. refine 작업을 생성하려면 refine을 보내세요.

텍스처를 입힐 preview 작업의 ID입니다. preview 작업의 상태는 SUCCEEDED여야 합니다.

기본 색상과 함께 PBR 맵(메탈릭, 러프니스, 노멀)도 생성할지 여부입니다.

ai_model이 meshy-6인 경우, texture_resolution: 8k를 제외하고 Meshy는 이미션 맵도 생성합니다. meshy-6-lite, meshy-7, meshy-7.1, latest는 이미션 맵을 생성하지 않습니다. ai_model을 설정하지 않은 meshy-t2 또는 meshy-t2.5 preview의 refine도 마찬가지입니다. ai_model: meshy-n1에서 true를 보내면 400이 반환됩니다.

기본 색상 텍스처의 해상도입니다. refine 작업에만 적용됩니다. preview에서 이 파라미터를 사용하면 400이 반환됩니다.

사용 가능한 값:

• 2k: 2048×2048
• 4k: 4096×4096
• 8k: 8192×8192

해상도가 높을수록 표면 디테일을 더 많이 담아냅니다. 4k와 8k는 ai_model이 meshy-6, meshy-7.1, 또는 latest여야 합니다. meshy-n1에서는 400이 반환됩니다. 8k에서는 Meshy가 이미션 맵을 생성하지 않습니다.

대신 texture_resolution을 보내세요. hd_texture: true는 texture_resolution: "4k"와 동일합니다. 둘 다 보내면 Meshy는 texture_resolution을 사용합니다.

텍스처링을 안내하는 텍스트로, 최대 800자입니다. 더 긴 텍스트는 400을 반환합니다. texture_prompt 또는 texture_image_url 중 하나만 보내세요. 둘 다 보내면 Meshy는 texture_prompt를 사용합니다. ai_model: meshy-n1에서 이를 보내면 400이 반환됩니다.

텍스처링을 안내하는 2D 이미지로, 공개 URL 또는 base64로 인코딩된 data URI로 지정합니다. 예: data:image/jpeg;base64,<your base64-encoded image data>.

이미지는 최대 20MB, 각 변이 최소 32픽셀, 최대 178,956,970픽셀(너비 × 높이)인 .jpg, .jpeg, .png, 또는 .webp 파일이어야 합니다.

ai_model: meshy-n1인 경우, Meshy는 이 이미지를 정면 뷰로 사용해 텍스처를 입힙니다.

메시에 텍스처를 입히는 AI 모델입니다.

사용 가능한 값:

• meshy-6-lite
• meshy-6
• meshy-7.1
• latest: Meshy 7.1
• meshy-n1: 참조 이미지만으로 만드는 2K 기본 색상 텍스처입니다. 텍스트 prompt, PBR 맵, 4K 또는 8K는 지원하지 않습니다.
• meshy-7(지원 중단): 대신 meshy-7.1을 보내세요

비워두면 preview 작업의 모델을 사용하므로, preview와 그 refine이 처음부터 끝까지 동일한 모델에서 실행됩니다. 값을 보내면 이를 재정의합니다. 명시적으로 latest를 보내면 preview 작업에서와 동일한 방식으로 해석되므로, latest preview와 그 latest refine은 항상 동일한 텍스처 모델을 사용합니다.

meshy-n1인 경우, Meshy는 texture_image_url로부터 텍스처를 입힙니다. 이를 보내지 않으면 Meshy는 meshy-7.1 또는 latest preview가 저장한 참조 이미지를 사용합니다. 다른 preview의 경우 texture_image_url을 보내지 않으면 400이 반환됩니다. preview는 최대 7,999,999개의 삼각형을 가질 수 있습니다. 쿼드로 리메시된 preview는 400을 반환합니다.

생성 전에 texture_prompt와 texture_image_url에 유해한 콘텐츠가 있는지 검사할지 여부입니다. Meshy가 유해한 콘텐츠를 감지하면 요청은 400을 반환하며 Meshy는 작업을 생성하지 않습니다.

기본 색상 텍스처에서 하이라이트와 그림자를 제거할지 여부입니다. 더 깔끔한 결과는 커스텀 조명 환경에서 더 잘 작동합니다.

ai_model이 meshy-6일 때만 적용됩니다. meshy-7.1과 latest는 이 값을 받아들이지만 무시하며, ai_model을 설정하지 않은 meshy-t2 또는 meshy-t2.5 preview의 refine도 마찬가지입니다. meshy-6-lite와 함께 보내면 400이 반환됩니다. meshy-n1에서 true를 보내면 400이 반환됩니다.

생성할 파일 형식입니다. Meshy는 이 형식들만 생성하여 반환하므로 작업 시간이 단축될 수 있습니다. 비워두면 Meshy는 3mf를 제외한 모든 형식을 생성하며, 3mf는 요청할 때만 생성합니다.

사용 가능한 값:

• glb
• obj
• fbx
• stl
• usdz
• 3mf

투명 배경(RGBA)의 미리보기도 함께 렌더링할지 여부입니다. 작업을 조회할 때 alpha_thumbnail_url로 반환됩니다. thumbnail_url은 변경되지 않습니다.

AI 비전으로 객체의 실제 높이를 추정하여 모델 크기를 그에 맞게 조정할지 여부입니다. origin_at을 설정하지 않으면 Meshy는 원점을 바닥에 둡니다.

요청을 실행할 수 없습니다. 오류 메시지에서 어떤 문제가 발견되었는지 알려줍니다. 예를 들면:

• 잘못된 작업 ID: preview_task_id가 유효하지 않거나, 회원님의 preview 작업과 일치하지 않습니다.
• 작업 준비 안 됨: preview 작업이 아직 성공하지 않았습니다.
• 모델 불일치: preview 작업의 AI 모델이 요청한 refine 모델과 맞지 않습니다.
• remove_lighting에 지원되지 않는 모델: ai_model: "meshy-6-lite"와 함께 remove_lighting을 보냈습니다.
• Meshy N1용 참조 이미지 없음: texture_image_url 없이 ai_model: meshy-n1을 보냈는데, preview에 Meshy N1이 사용할 수 있는 참조 이미지가 없습니다. texture_image_url을 보내세요.
• Meshy N1용 쿼드 preview: 쿼드로 리메시된 preview에 대해 ai_model: meshy-n1을 보냈습니다. 다른 ai_model로 refine하세요.
• Meshy N1의 삼각형 수 초과: ai_model: meshy-n1에서 preview의 삼각형 수가 7,999,999개를 초과합니다. 다른 ai_model로 refine하세요.
• Meshy N1에 지원되지 않는 옵션: 다음 옵션 중 하나와 함께 ai_model: meshy-n1을 보냈습니다:
  • texture_prompt
  • enable_pbr: true
  • 4k 또는 8k의 texture_resolution
  • texture_resolution 없이 hd_texture: true
  • remove_lighting: true

요청을 수정한 뒤 다시 보내세요. 오류를 참고하세요.

API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.

예를 들면:

• 크레딧 부족: 계정에 이 작업을 수행할 만큼 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. 크레딧 잔액을 확인한 뒤 다시 시도하세요.
• 무료 플랜: 작업을 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 뒤 다시 시도하세요.

콘텐츠 moderation이 prompt 또는 입력 이미지를 차단했습니다. 입력을 변경한 뒤 다시 시도하세요.

속도 제한을 초과했습니다. 잠시 기다린 뒤 다시 시도하세요. 속도 제한을 참고하세요.

생성 응답에서 제공된 작업 ID입니다.

삭제할 작업의 ID입니다.

반환할 페이지 번호이며, 최대 255까지 가능합니다. 더 큰 값을 입력하면 400을 반환합니다.

페이지당 작업 수이며, 최대 100까지 가능합니다.

정렬 순서입니다.

사용 가능한 값:

• +created_at: 오래된 순
• -created_at: 최신 순

생성 응답에서 받은 작업 ID입니다.

작업 ID입니다. 불투명한 문자열로 취급하고, 그 형식에 의존하지 마세요.

작업 유형으로, preview 작업의 경우 text-to-3d-preview, refine 작업의 경우 text-to-3d-refine입니다.

생성된 3D 모델의 다운로드 URL이며, 파일 형식별로 하나씩 제공됩니다. 작업에서 생성하지 않은 형식은 빈 문자열이 아니라 키 자체가 없습니다.

작업을 생성할 때 보낸 prompt로, 수정되지 않은 원본입니다.

refine 단계에서 텍스처링을 안내하기 위해 보낸 텍스트 prompt입니다.

대신 geometry_resolution을 참조하세요.

preview 작업이 실행된 Ultra 등급으로, 2k 또는 4k입니다. standard인 경우에는 이 필드가 없습니다.

텍스처링을 안내하기 위해 보낸 이미지의 다운로드 URL입니다.

3D 모델의 썸네일 이미지 다운로드 URL입니다.

thumbnail_url의 배경이 투명한(RGBA) 버전의 다운로드 URL입니다. alpha_thumbnail: true로 작업을 생성했고 Meshy가 투명 미리보기를 렌더링한 경우에만 존재합니다.

작업이 얼마나 진행되었는지를 백분율로 나타냅니다. 작업이 시작되기 전까지는 0이고, 성공하면 100입니다.

작업이 시작된 시간으로, 유닉스 밀리초 단위입니다. 작업이 시작되기 전까지는 0입니다.

작업이 생성된 시간으로, 유닉스 밀리초 단위입니다.

작업이 종료된 시간으로, 유닉스 밀리초 단위입니다. 작업이 종료되기 전까지는 0입니다.

작업 상태로, PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.

생성된 텍스처 맵의 다운로드 URL로, 객체 배열 형태입니다. 일반적으로 하나의 객체만 담겨 있습니다. 각 객체에는 다음 필드가 있습니다:

대기열에서 이 작업보다 앞에 있는 작업의 수입니다. 이 값은 작업이 PENDING 상태일 때만 의미가 있습니다.

작업이 실패했을 때의 오류 세부 정보입니다. 상태가 FAILED가 아니면 null입니다. 오류를 참조하세요.

작업에서 사용한 크레딧 수입니다. 상태가 PENDING, IN_PROGRESS, SUCCEEDED일 때 존재합니다. FAILED 작업의 경우 Meshy가 크레딧을 환불하므로 0입니다.