리텍스처 API는 Meshy의 AI 리텍스처 기능을 자체 애플리케이션에 통합할 수 있게 해주는 기능입니다. 이 섹션에서는 이 API를 시작하는 데 필요한 모든 정보를
확인할 수 있습니다.
POST/openapi/v1/retexture
리텍스처 작업 생성
이 엔드포인트를 사용하면 새 리텍스처 작업을 생성할 수 있습니다.
리텍스처 작업 객체를 참조하여
리텍스처 작업 객체에 포함되는 속성을 확인하세요.
파라미터
input_task_id 또는 model_url 중 하나만 필수입니다. 둘 다 제공되는 경우 input_task_id가 우선순위를 갖습니다.
Name
input_task_id
Type
string
필수
Description
리텍스처하려는 완료된 이미지로 3D 또는 텍스트로 3D 작업의 ID입니다.
이 작업은 다음 작업 중 하나여야 합니다: 텍스트로 3D Preview, 텍스트로 3D Refine, 이미지로 3D 또는 리메시. 또한 상태가 SUCCEEDED여야 합니다.
Name
model_url
Type
string
필수
Description
Meshy가 텍스처를 적용할 3D 모델을 제공하세요. 지원되는 형식: .glb, .gltf, .obj, .fbx, .stl.
모델을 제공하는 방법은 두 가지입니다:
공개적으로 접근 가능한 URL: 공용 인터넷에서 접근할 수 있는 URL입니다.
Data URI: 모델의 base64 인코딩된 Data URI입니다. MIME type application/octet-stream을 사용하세요. 예: data:application/octet-stream;base64,<your base64-encoded model data>.
text_style_prompt 또는 image_style_url 중 하나만 필수입니다. 둘 다 제공되는 경우 image_style_url이 우선순위를 갖습니다.
Name
text_style_prompt
Type
string
필수
Description
원하는 객체의 텍스처 스타일을 텍스트로 설명하세요. 최대 600자입니다.
Name
image_style_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>
원본 에셋과 업로드된 이미지 간에 지오메트리 차이가 상당한 경우 이미지 텍스처링이 최적으로 작동하지 않을 수 있습니다.
Name
ai_model
Type
string
기본값 latest
Description
리텍스처링에 사용할 AI 모델의 ID입니다. 사용 가능한 값: meshy-5, meshy-6, latest (Meshy 6).
Name
enable_original_uv
Type
boolean
기본값 false
Description
새 UV 레이아웃을 생성하는 대신 모델의 기존 UV 레이아웃을 유지합니다.
Meshy가 생성한 모델(input_task_id를 통해, 또는 Meshy 출력물을 가리키는 model_url)을 리텍스처하는 경우, 최적화된 UV 레이아웃을 재사용하려면 이 값을 true로 설정하세요.
업로드한 타사 모델을 리텍스처하는 경우, 유지하려는 좋은 UV가 이미 있으면 true로 설정하거나, Meshy가 새로운 UV를 언랩하도록 하려면 false로 두세요(적절한 UV 매핑이 없는 모델에 가장 적합).
Name
enable_pbr
Type
boolean
기본값 false
Description
기본 색상에 더해 PBR 맵(금속성, 거칠기, 노멀)을 생성합니다. ai_model이 meshy-6 또는 latest인 경우 이미션 맵도 포함됩니다.
Name
hd_texture
Type
boolean
기본값 false
Description
더 높은 디테일을 위해 기본 색상 텍스처를 4K(4096×4096) 해상도로 생성합니다.
ai_model이 meshy-6 또는 latest인 경우에만 지원됩니다. PBR 맵은 항상 2K로 생성됩니다.
Name
remove_lighting
Type
boolean
기본값 true
Description
기본 색상 텍스처에서 하이라이트와 그림자를 제거하여, 사용자 지정 조명 설정에서 더 잘 작동하는 깔끔한 결과를 생성합니다.
ai_model이 meshy-6 또는 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 필드는 변경되지 않습니다.
반환값
응답의 result 속성에는 새로 생성된 리텍스처 작업의 작업 id가 포함됩니다.
실패 모드
Name
400 - Bad Request
Description
요청을 수락할 수 없습니다. 일반적인 원인:
누락된 파라미터: model_url 또는 input_task_id를 제공해야 합니다.
누락된 스타일: text_style_prompt 또는 image_style_url을 제공해야 합니다.
잘못된 입력 작업: input_task_id는 지원되는 모델의 성공한 작업을 참조해야 합니다.
잘못된 모델 형식: model_url이 지원되지 않는 확장자를 가진 파일을 가리킵니다.
접근할 수 없는 URL: model_url 또는 image_style_url을 다운로드할 수 없습니다.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인하세요.
Name
402 - Payment Required
Description
이 작업을 수행하기 위한 크레딧이 부족합니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.
Request
POST
/openapi/v1/retexture
# Retexture with text promptcurl https://api.meshy.ai/openapi/v1/retexture \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style", "enable_original_uv": true, "enable_pbr": true }'# Retexture with image style and PBRcurl https://api.meshy.ai/openapi/v1/retexture \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg", "ai_model": "latest", "enable_pbr": true, "enable_original_uv": true }'
Response
{"result":"018a210d-8ba4-705c-b111-1f1776f7f578"}
GET/openapi/v1/retexture/:id
리텍스처 작업 조회
이 엔드포인트를 사용하면 유효한 작업 id로 리텍스처 작업을 조회할 수 있습니다.
리텍스처 작업 객체에 포함되는 속성을 확인하려면
리텍스처 작업 객체를 참조하세요.
매개변수
Name
id
Type
path
Description
조회할 리텍스처 작업의 고유 식별자입니다.
반환값
응답에는 리텍스처 작업 객체가 포함됩니다. 자세한 내용은
리텍스처 작업 객체 섹션을 확인하세요.
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","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=***","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=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","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" } ],"task_error": {"message":"" },"consumed_credits":10}
[ {"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","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=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","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":10 }]
리텍스처 작업 객체는 Meshy가 텍스트 또는 이미지 입력에서 3D 텍스처를 생성하는 데 사용하는 작업 단위입니다.
이 모델에는 다음 속성이 있습니다:
속성
Name
id
Type
string
Description
작업의 고유 식별자입니다. 구현 세부 사항으로 작업 id에 k-sortable UUID를 사용하지만,
id 형식에 대해 어떤 가정도 해서는 안 됩니다.
Name
type
Type
string
Description
리텍스처 작업의 유형입니다. 값은 retexture입니다.
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
MTL 파일의 다운로드 가능한 URL이며, 텍스처가 있는 경우 OBJ 내보내기와 함께 반환됩니다.
Name
stl
Type
string
Description
STL 파일의 다운로드 가능한 URL입니다.
Name
3mf
Type
string
Description
3MF 파일의 다운로드 가능한 URL입니다. target_formats를 통해 3mf가 요청된 경우에만 존재합니다.
Name
text_style_prompt
Type
string
Description
텍스처링 작업을 생성하는 데 사용된 텍스트 prompt입니다.
Name
image_style_url
Type
string
Description
텍스처링 작업을 생성하는 데 사용된 이미지 입력입니다.
Name
thumbnail_url
Type
string
Description
모델 파일의 썸네일 이미지에 대한 다운로드 가능한 URL입니다.
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url의 투명 배경(RGBA) 버전에 대한 다운로드 가능한 URL입니다. 작업이 alpha_thumbnail: true로 생성되고 투명 미리보기가 성공적으로 렌더링된 경우에만 존재하며, 그렇지 않으면 이 필드는 생략됩니다.
Name
progress
Type
integer
Description
작업의 progress입니다. 작업이 아직 시작되지 않은 경우 이 속성은 0입니다. 작업이 성공하면 100이 됩니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시점의 타임스탬프이며, 밀리초 단위입니다. 작업이 아직 시작되지 않은 경우 이 속성은 0입니다.
타임스탬프는 1970년 1월 1일 UTC 이후 경과한 밀리초 수를 나타내며,
RFC 3339 표준을 따릅니다.
예를 들어 2023년 9월 1일 금요일 오후 12:00:00 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인 경우 이 속성은 생략됩니다.
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 Retexture Task Model
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","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=***" },"text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","image_style_url":"https://assets.meshy.ai/***/image/example_image.jpg?Expires=***","thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","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":10}