텍스트로 3D API

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

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

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

mode	샘플 모델
미리보기
정제

텍스트로 3D 작업 스트리밍

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

매개변수

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

반환값

Server-Sent Events로 텍스트로 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

// 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 작업 객체는 Meshy가 텍스트 입력에서 3D 모델을 생성하기 위해 추적하는 작업 단위입니다. 텍스트로 3D API에는 preview와 refine의 두 단계가 있습니다. Preview 단계는 메시만 있는 3D 모델을 생성하기 위한 단계이고, refine 단계는 preview 단계의 결과를 기반으로 텍스처가 적용된 3D 모델을 생성하기 위한 단계입니다.

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

속성

Name
id
Type
string
Description
작업의 고유 식별자입니다. 구현 세부 사항으로 작업 id에는 k-정렬 가능 UUID를 사용하지만, 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입니다. target_formats를 통해 3mf가 요청된 경우에만 존재합니다.
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
개선 단계에서 텍스처링 과정을 안내하기 위해 제공되는 추가 텍스트 prompt입니다.
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
작업의 progress입니다. 작업이 아직 시작되지 않은 경우 이 속성은 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
  베이스 컬러 맵 이미지의 다운로드 가능한 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,
  "seed": 1234,
  "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
}

텍스트로 3D API

텍스트로 3D 미리보기 작업 생성

파라미터

반환

실패 모드

Request

Response

텍스트로 3D Refine 작업 생성

매개변수

반환값

실패 모드

Request

Response

텍스트로 3D 작업 조회

Parameters

Returns

Examples

Request

Response

텍스트로 3D 작업 삭제

경로 매개변수

반환값

Request

Response

텍스트로 3D 작업 목록 조회

매개변수

반환값

Request

Response

텍스트로 3D 작업 스트리밍

매개변수

반환값

Request

Response Stream

텍스트로 3D 작업 객체

속성

Example Text to 3D Task Object