이미지로 3D API

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

POST/openapi/v1/image-to-3d

이미지로 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/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-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/v1/image-to-3d

List Image to 3D Tasks

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

Parameters

Optional attributes

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

Returns

이미지로 3D 작업 객체의 페이지네이션된 목록을 반환합니다.

Request

GET

/openapi/v1/image-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "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=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "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": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

Image to 3D 작업 스트리밍

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

매개변수

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

반환값

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

PENDING 또는 IN_PROGRESS 상태의 작업의 경우, 응답 스트림에는 필요한 progress 및 status 필드만 포함됩니다.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-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",
  "type": "image-to-3d",
  "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=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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": 30
}

이미지로 3D 작업 객체

이미지로 3D 작업 객체는 이미지 입력으로부터 3D 모델을 생성하기 위해 Meshy가 추적하는 작업 단위입니다. 이 객체는 다음과 같은 속성을 가집니다:

속성

Name
id
Type
string
Description
작업의 고유 식별자입니다. 구현 세부 사항으로 작업 id에 k-sortable UUID를 사용하지만, id의 형식에 대해서는 어떠한 가정도 하지 말아야 합니다.
Name
type
Type
string
Description
이미지로 3D 작업의 유형입니다. 값은 image-to-3d입니다.
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
  pre_remeshed_glb
  Type
  string
  Description
  리메시 전 원본 GLB 출력물의 다운로드 가능한 URL입니다.
  작업이 should_remesh: true와 save_pre_remeshed_model: true를 모두 사용하여 생성된 경우에만 사용할 수 있습니다.
Name
thumbnail_url
Type
string
Description
모델 파일의 썸네일 이미지에 대한 다운로드 가능한 URL입니다. 존재할 경우 thumbnail_urls.front와 동일하며, 하위 호환성을 위해 유지됩니다.
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url의 투명 배경(RGBA) 버전에 대한 다운로드 가능한 URL입니다. 작업이 alpha_thumbnail: true로 생성되고 투명 미리보기가 성공적으로 렌더링된 경우에만 존재하며, 그렇지 않으면 이 필드는 생략됩니다.
Name
thumbnail_urls
Type
object
Description
생성된 3D 모델의 네 가지 기본 방향 썸네일에 대한 다운로드 가능한 URL입니다. 각 값은 thumbnail_url과 동일한 재질과 조명으로 렌더링된 512×512 PNG에 대한 서명된 URL입니다. GLB를 다운로드하지 않고도 배치 파이프라인에서 여러 각도로 모델을 미리 볼 때 유용합니다.
작업이 multi_view_thumbnails: true로 생성되고 SUCCEEDED 상태에 도달한 경우에만 존재합니다. 이전 작업이나 이 옵션 없이 생성된 작업에는 이 필드가 포함되지 않습니다.
- Name
  front
  Type
  string
  Description
  정면 뷰, 수직축 기준 0° 회전(thumbnail_url과 일치).
- Name
  right
  Type
  string
  Description
  오른쪽 뷰, 90° 회전.
- Name
  back
  Type
  string
  Description
  후면 뷰, 180° 회전.
- Name
  left
  Type
  string
  Description
  왼쪽 뷰, 270° 회전.
Name
texture_prompt
Type
string
Description
텍스처링 과정을 안내하는 데 사용된 텍스트 prompt입니다.
Name
texture_image_url
Type
string
Description
텍스처링 과정을 안내하는 데 사용된 텍스처 이미지의 다운로드 가능한 URL입니다.
Name
ultra_mode
Type
boolean
⚠ 사용 중단
Description
지원 중단됨; 대신 geometry_resolution을 참조하세요.
Name
geometry_resolution
Type
string
Description
작업이 실행된 Ultra 등급입니다(2k 또는 4k); standard의 경우 생략됩니다.
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 PM 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-6-lite, meshy-7.1, meshy-t2, 또는 latest인 경우, 이 속성은 생략됩니다.
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 Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

이미지로 3D API

이미지로 3D 작업 생성하기

파라미터

반환값

실패 모드

Request

Response

이미지로 3D 작업 조회

매개변수

반환값

Request

Response

이미지로 3D 작업 삭제

경로 매개변수

작업 상태

반환값

Request

Response

List Image to 3D Tasks

Parameters

Optional attributes

Returns

Request

Response

Image to 3D 작업 스트리밍

매개변수

반환값

Request

Response Stream

이미지로 3D 작업 객체

속성

Example Image to 3D Task Object