Retexture API

텍스트 prompt 또는 참조 이미지를 사용하여 기존 3D 모델에 대한 새로운 텍스처를 생성합니다. 모델은 다른 Meshy 작업에서 가져오거나 모델 파일로부터 가져올 수 있습니다.

POST/openapi/v1/retexture

리텍스처 작업 생성

리텍스처 작업을 생성합니다. 작업은 백그라운드에서 실행됩니다. 작업이 보통 얼마나 걸리는지는 처리 시간을 참고하세요.

Request

POST

/openapi/v1/retexture

# Retexture with text prompt
curl 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 PBR
curl 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": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "latest",
    "enable_pbr": true,
    "enable_original_uv": true
  }'

# Retexture with Meshy N1 from front and back views
curl 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",
    "ai_model": "meshy-n1",
    "multiview_image_urls": [
      "<your front view image url or data URI>",
      "<your back view image url or data URI>"
    ]
  }'

Response

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

파라미터

Name
input_task_id
Type
string
필수
Description
model_url을 보내지 않는 한 필수입니다. 텍스처를 적용할 3D 모델을 생성한 작업의 ID로, 예를 들어 텍스트로 3D, 이미지로 3D, 리메시, 또는 리텍스처 작업이 해당됩니다. 이 작업은 API로 생성했으며 상태가 SUCCEEDED여야 합니다. Meshy는 해당 작업의 GLB에 텍스처를 적용합니다.
meshy-n1에서는 작업의 모델이 삼각형 기준으로 최대 7,999,999개의 면(쿼드는 2개로 계산)을 가질 수 있습니다.

Name
model_url
Type
string
필수
Description
input_task_id를 보내지 않는 한 필수입니다. 텍스처를 적용할 모델로, 공개 URL 또는 data URI 형태입니다. 둘 다 보내면 Meshy는 input_task_id를 사용합니다.
모델은 http 또는 https URL에서 최대 400MB, 또는 data URI로 최대 100MB의 GLB, glTF, OBJ, FBX, 또는 STL 파일이어야 합니다. data URI의 경우 MIME type application/octet-stream을 사용하세요. 예: data:application/octet-stream;base64,<base64로 인코딩된 모델 데이터>.
100MB를 초과하는 파일은 다음 규칙도 따라야 합니다.
- GLB, glTF, FBX, 또는 OBJ 파일은 최대 10,000,000개의 면을 가질 수 있습니다. Meshy는 면을 삼각형 기준으로 계산하므로 쿼드는 2개로, 두 번 이상 그려진 메시는 복사본마다 1개로 계산됩니다.
- FBX 파일은 바이너리 FBX 7.1 이상이어야 합니다.
- GLB 또는 glTF 파일은 Draco 압축을 사용해서는 안 됩니다.
meshy-n1에서는 파일 크기와 관계없이 모델이 삼각형 기준으로 최대 7,999,999개의 면(쿼드는 2개로 계산)을 가질 수 있습니다.

다음 세 가지 스타일 입력 중 하나를 보내세요.

Name
text_style_prompt
Type
string
필수
Description
image_style_url 또는 multiview_image_urls를 보내지 않는 한 필수입니다. 원하는 텍스처를 설명하는 텍스트로, 최대 800자입니다. 더 긴 텍스트는 400을 반환합니다. meshy-n1에서 image_style_url 없이 보내면 400을 반환합니다.

Name
image_style_url
Type
string
필수
Description
text_style_prompt 또는 multiview_image_urls를 보내지 않는 한 필수입니다. 텍스처가 따를 스타일을 가진 2D 이미지로, 공개 URL 또는 data URI(data:image/jpeg;base64,<base64로 인코딩된 이미지 데이터>) 형태입니다. text_style_prompt와 image_style_url을 모두 보내면 Meshy는 image_style_url을 사용합니다.
이미지는 .jpg, .jpeg, .png, 또는 .webp 파일이어야 하며, 최대 20MB, 각 변 최소 32픽셀이어야 합니다.
이미지 속 객체가 모델과 매우 다른 형태일 경우 텍스처가 잘 맞지 않을 수 있습니다. meshy-n1에서는 Meshy가 해당 이미지를 정면 뷰로 처리합니다.

Name
multiview_image_urls
Type
string[]
필수
Description
text_style_prompt 또는 image_style_url을 보내지 않는 한 필수입니다. 서로 다른 뷰에서 촬영한 동일한 객체의 이미지 1~4장입니다. 첫 번째 이미지는 메인(정면) 뷰입니다. 다른 뷰(왼쪽, 뒤, 오른쪽)의 순서는 상관없습니다. 빈 배열이거나 이미지가 4장을 초과하면 400을 반환합니다.
각 이미지는 image_style_url과 동일한 형식 및 크기 규칙을 따르며, 이미지당 최대 20MB입니다. multiview_image_urls는 text_style_prompt 또는 image_style_url과 함께 사용할 수 없습니다.
multiview_image_urls를 사용하려면 ai_model을 meshy-7 또는 meshy-n1로 명시적으로 지정해야 합니다. 기본값인 latest를 포함해 다른 ai_model을 사용하면 400을 반환합니다.

Name
ai_model
Type
string
기본값 latest
Description
텍스처를 생성하는 AI 모델입니다.
사용 가능한 값:
- meshy-6-lite
- meshy-6
- meshy-7
- meshy-n1: 참조 이미지만으로 생성되는 2K 베이스 컬러 텍스처입니다. 텍스트 prompt, PBR 맵, 4K 또는 8K는 지원하지 않습니다. 최대 7,999,999개의 면까지 지원합니다.
- latest: Meshy 7
Name
enable_original_uv
Type
boolean
기본값 false
Description
새 UV 레이아웃을 생성하는 대신 모델의 UV 레이아웃을 유지할지 여부입니다.
- Meshy가 생성한 모델, 즉 input_task_id에서 가져오거나 Meshy 출력물을 가리키는 model_url인 경우, true로 설정하여 최적화된 UV 레이아웃을 재사용하세요.
- 다른 곳에서 업로드한 모델의 경우, 이미 좋은 상태인 UV를 유지하려면 true로 설정하세요. false로 두면 Meshy가 새 UV를 생성하며, 이는 적절한 UV 매핑이 없는 모델에 적합합니다.
Name
enable_pbr
Type
boolean
기본값 false
Description
베이스 컬러와 함께 PBR 맵(메탈릭, 러프니스, 노멀)도 생성할지 여부입니다. meshy-6에서는 texture_resolution이 8k인 경우를 제외하고 Meshy가 emission 맵도 생성합니다. meshy-6-lite, meshy-7, latest는 emission 맵을 생성하지 않습니다. meshy-n1에서 true로 설정하면 400을 반환합니다.
Name
texture_resolution
Type
string
기본값 2k
Description
베이스 컬러 텍스처의 크기입니다. 해상도가 높을수록 표면의 세부 사항을 더 많이 담아냅니다.
사용 가능한 값:
- 2k: 2048 × 2048픽셀
- 4k: 4096 × 4096픽셀
- 8k: 8192 × 8192픽셀
4k와 8k는 ai_model이 meshy-6, meshy-7, 또는 latest여야 합니다. meshy-6-lite 또는 meshy-n1에서는 400을 반환합니다. 8k에서는 Meshy가 emission 맵을 생성하지 않습니다.
Name
hd_texture
Type
boolean
⚠ 사용 중단
기본값 false
Description
대신 texture_resolution을 사용하세요. true는 texture_resolution: "4k"와 동일합니다. 둘 다 보내면 Meshy는 texture_resolution을 사용합니다.
Name
remove_lighting
Type
boolean
기본값 true
Description
베이스 컬러 텍스처에서 하이라이트와 그림자를 제거할지 여부입니다. 결과물은 사용자가 설정한 조명에서 더 잘 작동합니다.
Meshy는 meshy-6에서 texture_resolution이 2k 또는 4k일 때만 이를 적용합니다. meshy-7 또는 latest에서나 8k에서는 Meshy가 이 값을 받아들이되 무시합니다. meshy-6-lite 또는 meshy-n1에서는 어떤 값을 보내도 400을 반환합니다.
Name
target_formats
Type
string[]
Description
생성할 파일 형식입니다. Meshy는 목록에 있는 형식만 생성하여 작업 시간을 단축할 수 있습니다. 생략하면 Meshy는 3mf를 제외한 모든 형식을 생성합니다.
사용 가능한 값:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
기본값 false
Description
투명 배경(RGBA)을 가진 미리보기도 함께 렌더링할지 여부입니다. 이 미리보기는 작업을 조회할 때 alpha_thumbnail_url로 반환됩니다. thumbnail_url은 변경되지 않습니다.

반환값

응답의 result 필드에는 새 리텍스처 작업의 ID가 담깁니다.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 오류 메시지에 발견된 문제가 표시됩니다. 예시:
- 파라미터 누락: model_url과 input_task_id 둘 다 보내지 않았습니다.
- 스타일 누락: text_style_prompt, image_style_url, multiview_image_urls 중 어느 것도 보내지 않았습니다.
- 스타일 입력 충돌: multiview_image_urls를 text_style_prompt 또는 image_style_url과 함께 보냈습니다.
- 멀티뷰에 지원되지 않는 모델: ai_model을 meshy-7 또는 meshy-n1로 명시하지 않고 multiview_image_urls를 보냈습니다.
- Meshy N1에서 지원되지 않는 옵션: meshy-n1과 함께 enable_pbr: true, remove_lighting, 4k 또는 8k의 texture_resolution, texture_resolution 없는 hd_texture: true, 또는 image_style_url 없는 text_style_prompt를 보냈습니다.
- Meshy N1에서 삼각형이 너무 많음: meshy-n1에서 3D 모델의 삼각형 수가 7,999,999개를 초과합니다. 삼각형 수를 줄이거나 다른 ai_model을 사용하세요.
- Meshy N1에서 모델이 너무 복잡함: meshy-n1에서 model_url 파일이 너무 복잡하여 Meshy가 삼각형 수를 셀 수 없습니다. 삼각형 수를 줄인 후 파일을 다시 보내세요.
- 삼각형 수 계산 시간 초과: meshy-n1에서 model_url 파일의 삼각형 수를 세는 데 시간이 너무 오래 걸렸습니다. 다시 시도하거나 모델 크기를 줄이세요.
- 유효하지 않은 입력 작업: input_task_id가 지원되는 유형의 성공한 작업이 아닙니다.
- 유효하지 않은 모델 형식: model_url 파일의 확장자가 지원되지 않습니다.
- 접근할 수 없는 URL: Meshy가 model_url 파일, image_style_url 이미지, 또는 multiview_image_urls 이미지를 다운로드할 수 없습니다.
- 모델 파일이 너무 큼: model_url 파일이 http 또는 https URL에서 400MB를 초과하거나, data URI로 100MB를 초과합니다.
- 면이 너무 많음: model_url 파일이 100MB를 초과하며 면이 10,000,000개를 초과합니다. 면 수를 줄인 후 파일을 다시 보내세요.
- 100MB를 초과하는 ASCII FBX: model_url 파일이 100MB를 초과하는 ASCII FBX입니다. 바이너리 FBX 또는 GLB로 보내세요.
- 읽을 수 없는 모델 파일: model_url 파일이 100MB를 초과하며, Meshy가 헤더를 읽을 수 없습니다. 예를 들어 Draco로 압축된 GLB 또는 glTF이거나, 7.1 이전 버전의 바이너리 FBX입니다.
- 모델 헤더가 너무 복잡함: model_url 파일이 100MB를 초과하며, 헤더에 확인해야 할 메시, 노드, 또는 레코드가 너무 많습니다. 파일 내 객체 수를 줄인 후 다시 보내세요.
- 이미지가 너무 큼: image_style_url 이미지 또는 multiview_image_urls 이미지가 20MB를 초과합니다.
meshy-n1에서는 STL 파일처럼 Meshy가 작업 시작 전에 확인할 수 없는 모델은 여기서 거부되지 않습니다. 삼각형 수가 7,999,999개를 초과하면 작업이 실패하며, Meshy는 해당 크레딧을 환불합니다.
요청을 수정한 후 다시 보내세요. 오류를 참고하세요.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
예시:
- 크레딧 부족: 계정에 이 작업을 수행할 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다. 크레딧 잔액을 확인한 후 다시 시도하세요.
- 무료 플랜: 작업을 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 후 다시 시도하세요.
Name
403 - Forbidden
Description
다음 중 하나가 해당됩니다.
- 콘텐츠 moderation이 prompt 또는 입력 이미지를 차단했습니다. 입력을 변경한 후 다시 시도하세요.
- input_task_id가 양각 모델이며, 이 엔드포인트는 이를 리텍스처할 수 없습니다. 메시지는 This model type does not support this operation입니다. 다른 모델을 보내세요.
Name
404 - Not Found
Description
input_task_id가 사용자의 작업과 일치하지 않습니다. 작업 ID를 확인한 후 요청을 다시 보내세요.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다. 잠시 기다린 후 다시 시도하세요. 속도 제한을 참고하세요.

GET/openapi/v1/retexture/:id

리텍스처 작업 가져오기

ID로 리텍스처 작업을 반환합니다.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "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"
    }
  ],
  "task_error": null,

  "consumed_credits": 10
}

매개변수

Name
id
Type
path
Description
생성 응답에서 얻은 작업 ID입니다.

반환값

리텍스처 작업 객체를 반환합니다.

DELETE/openapi/v1/retexture/:id

리텍스처 작업 삭제

리텍스처 작업을 모델 및 데이터를 포함하여 영구적으로 삭제합니다. 삭제는 되돌릴 수 없습니다.

Request

DELETE

/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -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 keeps 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."
}

경로 매개변수

Name
id
Type
path
Description
삭제할 작업의 ID입니다.

작업 상태

PENDING 작업을 삭제하면 작업을 생성할 때 사용한 크레딧이 환불됩니다.

IN_PROGRESS 작업은 삭제할 수 없습니다. 요청은 409 Conflict를 반환하며, 작업은 계속 실행됩니다. Meshy는 이미 시작된 작업에 대해서는 환불을 제공하지 않으므로, 해당 작업을 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. 작업이 SUCCEEDED, FAILED, 또는 CANCELED 상태에 도달할 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)의 작업을 삭제해도 크레딧은 환불되지 않습니다.

반환값

작업이 삭제되면 200 OK를 반환하고, 작업이 IN_PROGRESS 상태이면 409 Conflict를 반환합니다.

GET/openapi/v1/retexture

리텍스처 작업 목록 조회

회원님의 리텍스처 작업 목록을 반환합니다.

Request

GET

/openapi/v1/retexture

curl https://api.meshy.ai/openapi/v1/retexture?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "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"
      }
    ],
    "task_error": null,

    "consumed_credits": 10
  }
]

매개변수

Name
page_num
Type
integer
기본값 1
Description
반환할 페이지 번호이며, 최대 255까지 가능합니다. 더 큰 값을 입력하면 400을 반환합니다.
Name
page_size
Type
integer
기본값 10
Description
페이지당 작업 수이며, 최대 100까지 가능합니다.
Name
sort_by
Type
string
Description
정렬 순서입니다.
사용 가능한 값:
- +created_at: 오래된 순
- -created_at: 최신 순

반환값

리텍스처 작업 객체의 페이지네이션된 목록입니다.

GET/openapi/v1/retexture/:id/stream

리텍스처 작업 스트리밍하기

리텍스처 작업의 업데이트를 Server-Sent Events (SSE)로 스트리밍합니다.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/retexture/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.
// These examples are shortened. Each event holds the full task object.
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": "retexture",
  "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=***",
    "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=***"
  },
  "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"
    }
  ],
  "task_error": null,

  "consumed_credits": 10
}

Parameters

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

Returns

리텍스처 작업 객체의 스트림을 Server-Sent Events로 반환합니다.

각 이벤트는 Get 엔드포인트가 반환하는 것과 동일한 형태로 전체 작업 객체를 담고 있습니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 결과 필드에 아직 값이 없습니다.

리텍스처 작업 객체

리텍스처 작업 객체는 3D 모델에 대한 하나의 리텍스처 작업을 설명합니다. 여기에는 상태, progress, 그리고 작업이 성공했을 때의 모델 및 텍스처 파일이 담겨 있습니다.

속성

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"
    }
  ],
  "task_error": null,

  "consumed_credits": 10
}

Name
id
Type
string
Description
작업 ID입니다. 불투명한 문자열로 취급하고, 그 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형으로, 항상 retexture입니다.
Name
model_urls
Type
object
Description
텍스처가 적용된 3D 모델의 다운로드 URL이며, 파일 형식마다 하나씩 있습니다.
- Name
  glb
  Type
  string
  Description
  GLB 파일입니다.
- Name
  fbx
  Type
  string
  Description
  FBX 파일입니다.
- Name
  obj
  Type
  string
  Description
  OBJ 파일입니다.
- Name
  usdz
  Type
  string
  Description
  USDZ 파일입니다.
- Name
  mtl
  Type
  string
  Description
  MTL 파일입니다. 모델에 텍스처가 있는 경우 Meshy는 OBJ 파일과 함께 이 파일을 반환합니다.
- Name
  stl
  Type
  string
  Description
  STL 파일입니다.
- Name
  3mf
  Type
  string
  Description
  3MF 파일입니다. target_formats에 3mf가 포함된 경우에만 존재합니다.
Name
text_style_prompt
Type
string
Description
작업을 생성할 때 사용한 텍스트 prompt입니다.
Name
image_style_url
Type
string
Description
작업을 생성할 때 사용한 스타일 이미지입니다.
Name
multiview_image_urls
Type
string[]
Description
작업을 생성할 때 사용한 멀티뷰 참조 이미지의 다운로드 URL입니다. multiview_image_urls로 작업을 생성한 경우에만 존재합니다.
Name
thumbnail_url
Type
string
Description
모델의 썸네일 이미지를 위한 다운로드 URL입니다.
Name
alpha_thumbnail_url
Type
string
Description
투명 배경(RGBA)이 적용된 thumbnail_url 버전의 다운로드 URL입니다. alpha_thumbnail: true로 작업을 생성하고 Meshy가 투명 미리보기를 렌더링한 경우에만 존재합니다.
Name
progress
Type
integer
Description
작업이 완료된 정도를 백분율로 나타낸 값입니다. 작업이 시작되기 전까지는 0이며, 성공하면 100이 됩니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시각으로, 유닉스 밀리초 단위입니다. 작업이 시작되기 전까지는 0입니다.
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이며, 객체 배열 형태입니다. 이 배열에는 보통 객체 하나가 들어 있습니다. 각 객체에는 다음 필드가 있습니다:
- Name
  base_color
  Type
  string
  Description
  베이스 컬러 맵의 다운로드 URL입니다.
- Name
  metallic
  Type
  string
  Description
  메탈릭 맵의 다운로드 URL입니다. enable_pbr: false로 작업을 생성하면 Meshy는 이 필드를 생략합니다.
- Name
  normal
  Type
  string
  Description
  노멀 맵의 다운로드 URL입니다. enable_pbr: false로 작업을 생성하면 Meshy는 이 필드를 생략합니다.
- Name
  roughness
  Type
  string
  Description
  러프니스 맵의 다운로드 URL입니다. enable_pbr: false로 작업을 생성하면 Meshy는 이 필드를 생략합니다.
- Name
  emission
  Type
  string
  Description
  이미션 맵의 다운로드 URL입니다. 다음 중 하나로 작업을 생성하면 Meshy는 이 필드를 생략합니다:
  
  enable_pbr: false
  
  ai_model이 meshy-6-lite, meshy-7, 또는 latest인 경우
  
  texture_resolution: 8k
Name
preceding_tasks
Type
integer
Description
대기열에서 이 작업보다 앞에 있는 작업의 수입니다. 작업이 PENDING 상태일 때만 존재하며, 값이 0이면 필드가 생략됩니다.
Name
task_error
Type
object
Description
작업이 실패했을 때의 오류 세부 정보입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
작업에 사용된 크레딧 수입니다. 상태가 PENDING, IN_PROGRESS, SUCCEEDED일 때 존재합니다. FAILED 작업의 경우 Meshy가 작업 실패 시 크레딧을 환불하므로 0입니다.