Creative Lab 냉장고 자석 API

사진을 두 단계에 걸쳐 색상이 입혀진 양각과 평평한 뒷면을 가진 3D 프린팅용 냉장고 자석으로 변환합니다. 프로토타입 작업은 사진으로부터 색상화된 콘셉트 이미지를 생성합니다. 빌드 작업은 해당 이미지를 양각 3D 모델로 변환하며, 프로토타입 작업의 ID를 input_task_id로 사용합니다.

POST /openapi/creative-lab/fridge-magnet/v1/prototype
POST /openapi/creative-lab/fridge-magnet/v1/build

POST/openapi/creative-lab/fridge-magnet/v1/prototype

냉장고 자석 프로토타입 작업 생성하기

사진으로부터 색상이 적용된 컨셉 이미지 하나를 생성합니다. 3D 모델을 빌드하려면 이 작업의 ID를 빌드 엔드포인트에 input_task_id로 전달하세요. 작업의 필드에 대해서는 냉장고 자석 프로토타입 작업 객체를 참조하세요.

Request

POST

/openapi/creative-lab/fridge-magnet/v1/prototype

# Stage 1: generate a colorized fridge magnet concept image
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

{
  "result": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9"
}

Prototype example

Start with a source photo, then generate the prototype image used by the fridge magnet build stage.

Source landscape photo used as the Creative Lab Fridge Magnet input — Prototype input

Creative Lab Fridge Magnet prototype output generated from the source photo — Prototype output

매개변수

Name
image_url
Type
string
필수
Description
냉장고 자석 컨셉 이미지로 변환할 사진으로, 공개 URL 또는 data URI(data:image/jpeg;base64,<your base64-encoded image data>) 형식입니다.
이미지는 20MB 이하의 JPG, JPEG, PNG, 또는 WebP 파일이어야 합니다.
Name
name
Type
string
Description
작업의 이름으로, 최대 100자까지 지정할 수 있습니다. 이 값은 작업의 name 필드로 반환됩니다. 이름이 너무 길면 400이 반환됩니다.
Name
remove_background
Type
boolean
기본값 false
Description
프로토타입 이미지에서 배경을 제거할지 여부입니다. true로 설정하면 자석 전체를 유지한 투명 RGBA PNG가 반환되므로, 어떤 배경 위에든 배치할 수 있습니다. 빌드 역시 배경이 제거된 이미지에서 시작됩니다. Meshy가 배경을 제거할 수 없는 경우, 배경이 있는 상태의 이미지를 반환하며 작업은 그대로 성공 처리됩니다.
빌드의 remove_background 옵션은 이와 별개입니다.

반환값

result 필드에는 새로 생성된 프로토타입 작업의 ID가 담깁니다. status가 SUCCEEDED가 될 때까지 작업을 조회하거나 스트리밍하세요. 그런 다음 해당 ID를 빌드 엔드포인트에 input_task_id로 전달합니다.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 예를 들면 다음과 같습니다:
- image_url이 누락됨.
- 이미지가 JPG, JPEG, PNG, 또는 WebP 파일이 아님.
- 이미지가 너무 작거나, 20MB를 초과하거나, 최대 픽셀 수를 초과함.
- 예를 들어 URL이 404를 반환하거나 시간 초과가 발생하여 Meshy가 이미지를 다운로드할 수 없음.
- data URI가 유효한 base64가 아님.
- 이미지가 NSFW로 플래그됨.
오류 메시지에 어떤 문제가 발견되었는지 표시됩니다. 요청을 수정한 후 다시 전송하세요.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
다음 중 하나에 해당합니다:
- 계정에 크레딧이 충분하지 않음.
- API 키, 작업 공간, 또는 멤버가 크레딧 한도에 도달함.
- 계정이 무료 요금제임.
크레딧과 요금제를 확인한 후 다시 시도하세요.
Name
403 - Forbidden
Description
팀의 IP 필터링이 켜져 있고, Meshy가 해당 이미지를 제3자 지적 재산권 문제로 플래그했습니다. 사용 권한이 있는 이미지를 전송하세요.
Name
429 - Too Many Requests
Description
다음 한도 중 하나에 도달했습니다:
- 속도 제한을 초과하는 요청을 전송함. 몇 초 기다린 후 다시 시도하세요. 속도 제한을 참조하세요.
- 대기 중이거나 실행 중인 작업이 너무 많음. 일부가 완료될 때까지 기다린 후 다시 시도하세요.
- 크레딧이 남아 있지 않은 무제한 요금제에서 크레딧 없이 실행할 수 있는 작업 수에 도달함. 작업이 완료되기를 기다리거나 크레딧을 추가하세요.
Name
500 - Internal Server Error
Description
Meshy에서 서버 오류가 발생했습니다. 예를 들어 이미지에 대한 지적 재산권 검사를 실행할 수 없었던 경우입니다. Meshy는 작업을 생성하지 않으며, 청구된 크레딧이 있다면 환불합니다. 요청을 다시 시도하세요.

POST/openapi/creative-lab/fridge-magnet/v1/build

냉장고 자석 빌드 작업 생성하기

성공한 프로토타입 작업으로부터 3D 프린팅이 가능한 냉장고 자석을 생성합니다. Meshy는 프로토타입의 컨셉 이미지를 깊이 맵 릴리프로 변환하고, 선택한 형식의 모델 파일 하나를 반환합니다. 작업의 필드에 대해서는 냉장고 자석 빌드 작업 객체를 참고하세요.

Request

POST

/openapi/creative-lab/fridge-magnet/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
    "options": {
      "badge_shape": "rounded-rect",
      "size_mm": 60,
      "relief_height_mm": 3.3
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0"
}

Build example

The build task turns the selected prototype image into a 3D-printable fridge magnet model.

Creative Lab Fridge Magnet build model preview — Build model preview

파라미터

Name
input_task_id
Type
string
필수
Description
빌드할 프로토타입 작업의 ID입니다. POST /openapi/creative-lab/fridge-magnet/v1/prototype로 본인 계정이 생성했고, 상태가 SUCCEEDED인 작업이어야 합니다.
API를 통해 생성한 냉장고 자석 프로토타입 작업이 아닌 ID는 웹 앱에서 만든 프로토타입을 포함해 404를 반환합니다.
Name
name
Type
string
Description
작업의 이름으로, 최대 100자까지 가능합니다. 작업의 name 필드에 그대로 반환됩니다. 더 긴 이름은 400을 반환합니다.

`options`

릴리프의 형태에 대한 선택적 설정입니다. 모든 필드에는 기본값이 있으므로, 변경하고 싶은 필드만 전송하면 됩니다. 필드의 범위를 벗어난 값은 400을 반환합니다.

Name
badge_shape
Type
string
기본값 rounded-rect
Description
Meshy가 대상에서 윤곽선을 추적하지 않을 때 사용하는 자석의 외곽선입니다. remove_background가 false이거나, 대상의 윤곽선을 찾을 수 없을 때 Meshy가 이를 사용합니다.
사용 가능한 값:
- circle
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
기본값 60
Description
자석의 경계 사각형 변의 길이로, 밀리미터 단위이며 최대 400까지 가능합니다. 0은 기본값을 사용합니다.
Name
relief_height_mm
Type
number
기본값 3.3
Description
베이스 위로 올라가는 릴리프의 최대 높이로, 밀리미터 단위이며 0부터 20까지입니다.
Name
relief_offset_mm
Type
number
기본값 0
Description
릴리프를 얼마나 낮출지로, 밀리미터 단위이며 0부터 20까지입니다. Meshy는 이 값을 릴리프 높이 전체에서 베이스까지 빼줍니다.
Name
base_thickness_mm
Type
number
기본값 2.0
Description
릴리프 뒤의 평평한 베이스 판의 두께로, 밀리미터 단위이며 0부터 20까지입니다. 기본값인 2mm 베이스는 자석이 냉장고에 충분히 붙을 수 있는 두께를 제공해, 릴리프가 약하게 느껴지지 않도록 합니다.
Name
has_closed_back
Type
boolean
기본값 true
Description
자석의 뒷면, 즉 자석을 붙이는 쪽을 막을지 여부입니다. false는 뒷면을 셸(shell) 형태로 열어둡니다.
Name
relief_curve
Type
string
기본값 linear
Description
깊이 맵 값을 릴리프 높이로 매핑하는 커브입니다.
사용 가능한 값:
- linear
- gamma
- s-curve
Name
curve_param
Type
number
기본값 1.0
Description
커브의 강도로, 최대 10까지입니다. gamma와 s-curve 커브에서 사용되며, linear에서는 무시됩니다. 0은 기본값을 사용합니다.
Name
invert_depth
Type
boolean
기본값 false
Description
깊이 맵을 반전시켜, 더 어두운 영역이 더 높은 릴리프가 되도록 할지 여부입니다.
Name
smoothing
Type
number
기본값 0.24
Description
Meshy가 릴리프를 만들기 전에 깊이 맵을 얼마나 부드럽게 처리할지로, 0부터 10까지입니다.
Name
relief_scale
Type
number
기본값 1.0
Description
외곽선 안에서 중심을 기준으로 릴리프와 그 텍스처를 얼마나 확대할지로, 최대 10까지입니다. 1보다 큰 값은 대상을 확대하고, 1보다 작은 값은 축소합니다. 릴리프의 높이는 변경되지 않습니다. 0은 기본값을 사용합니다.
Name
depth_threshold
Type
number
기본값 0.1
Description
Meshy가 깊이를 0으로 설정하는 기준이 되는 깊이 맵 값으로, 0부터 1까지입니다.
Name
remove_background
Type
boolean
기본값 true
Description
대상에서 자석의 윤곽선을 추적해, 자석이 대상의 형태를 따르도록 할지 여부입니다. false는 대신 badge_shape 외곽선을 사용합니다. Meshy는 대상의 윤곽선을 찾을 수 없을 때도 badge_shape를 사용합니다.
이것은 프로토타입 이미지의 배경을 투명하게 할지 설정하는 프로토타입의 remove_background 파라미터와는 별개입니다.
Name
export_resolution
Type
integer
기본값 512
Description
내보낸 모델의 메시 해상도로, 64부터 512까지입니다. Meshy는 512픽셀 깊이 맵으로 지오메트리를 생성하므로, 더 세밀한 메시는 디테일을 추가하지 않고 면(face)만 추가합니다. 0은 기본값을 사용합니다.

`output`

선택 사항입니다. 빌드가 반환하는 파일 형식을 설정합니다.

Name
format
Type
string
기본값 glb
Description
빌드가 반환하는 파일 형식입니다.
사용 가능한 값:
- glb: model_urls.glb에 담긴 단일 model.glb 파일
- obj: model_urls.obj에 담긴 model.obj, model.mtl, texture.png가 포함된 zip 파일
- zip: model_urls.bundle_zip에 담긴, Meshy가 생성하는 모든 파일이 포함된 zip 파일

반환 값

result 필드에는 새 빌드 작업의 ID가 담깁니다. status가 SUCCEEDED가 될 때까지 작업을 조회하거나 스트리밍하세요. 그런 다음 model_urls의 단일 항목에서 파일을 다운로드하세요.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 예를 들면:
- input_task_id가 없거나 유효한 작업 ID가 아닙니다.
- 프로토타입 작업의 상태가 SUCCEEDED가 아닙니다. 아직 실행 중이라면 기다렸다가 다시 시도하세요. 실패했거나 취소되었다면 새 프로토타입 작업을 생성하세요.
- 프로토타입 작업은 성공했지만 이미지가 없습니다. 새 프로토타입 작업을 생성하세요.
- options 필드가 범위를 벗어났거나 사용 가능한 값이 아닙니다.
오류 메시지에 어떤 문제가 발견되었는지 나와 있습니다.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
다음 중 하나에 해당합니다:
- 계정에 크레딧이 충분하지 않습니다.
- API 키, 작업 공간 또는 멤버가 크레딧 한도에 도달했습니다.
- 계정이 무료 플랜을 사용 중입니다.
크레딧과 플랜을 확인한 뒤 다시 시도하세요.
Name
404 - Not Found
Description
input_task_id가 본인 계정이 API로 생성한 냉장고 자석 프로토타입 작업과 일치하지 않습니다. 웹 앱에서 만든 프로토타입도 404를 반환합니다. 프로토타입 생성 응답의 result ID를 전송하세요.
Name
429 - Too Many Requests
Description
다음 한도 중 하나에 도달했습니다:
- 속도 제한이 허용하는 것보다 더 많은 요청을 보냈습니다. 몇 초 기다렸다가 다시 시도하세요. 속도 제한을 참고하세요.
- 대기 중이거나 실행 중인 작업이 너무 많습니다. 일부가 끝날 때까지 기다렸다가 다시 시도하세요.
- 크레딧이 남아 있지 않은 무제한 플랜에서, 크레딧 없이 실행할 수 있는 작업 수에 도달했습니다. 작업이 끝날 때까지 기다리거나 크레딧을 추가하세요.

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id

Fridge Magnet 작업 가져오기

prototype 또는 build 작업을 반환합니다. 경로는 작업의 단계와 일치해야 합니다. /prototype/:id를 통해 요청된 build 작업은 404를 반환하며, /build/:id를 통해 요청된 prototype 작업도 마찬가지입니다.

필드에 대한 내용은 Fridge Magnet prototype 작업 객체와 Fridge Magnet build 작업 객체를 참고하세요.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
  "type": "creative-lab-fridge-magnet-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543210000,
  "started_at": 1729543215000,
  "finished_at": 1729543242000,
  "expires_at": 1729802442000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

매개변수

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

반환값

경로의 단계에 맞는 prototype 작업 객체 또는 build 작업 객체입니다.

실패 모드

Name
400 - Bad Request
Description
id가 유효한 작업 ID가 아닙니다. 생성 응답에서 받은 result ID를 전송하세요.
Name
403 - Forbidden
Description
팀에 IP 필터링이 활성화되어 있고, Meshy가 prototype 작업의 이미지를 제3자 지적 재산권 문제로 플래그했습니다. Build 작업과 Enterprise 플랜의 팀에는 이 오류가 발생하지 않습니다. 사용 권한이 있는 이미지로 prototype 작업을 생성하세요.
Name
404 - Not Found
Description
이 ID를 가진 Fridge Magnet 작업이 계정에 없거나, 작업의 단계가 경로와 일치하지 않습니다. ID를 확인하고, 작업에 맞게 /prototype 또는 /build를 사용하세요.
Name
500 - Internal Server Error
Description
Meshy가 지적 재산권 검사를 실행하지 못했습니다. 요청을 다시 시도하세요.

DELETE/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id

냉장고 자석 작업 삭제

냉장고 자석 작업을 취소합니다. PENDING 상태의 작업을 취소하면 크레딧이 환불됩니다. IN_PROGRESS 작업은 이미 워커가 작업을 시작했기 때문에 환불 없이 취소됩니다. 최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)인 작업은 취소할 수 없습니다.

경로는 작업의 단계와 일치해야 합니다. 예를 들어, 빌드 작업의 ID로 /prototype/:id에 DELETE를 호출하면 404가 반환됩니다.

Request

DELETE

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

경로 매개변수

Name
id
Type
path
Description
취소할 작업의 ID입니다.

반환값

빈 본문과 함께 204 No Content를 반환합니다.

실패 모드

Name
400 - Bad Request
Description
다음 중 하나에 해당합니다:
- id가 유효한 작업 ID가 아닙니다. 생성 응답의 result ID를 보내세요.
- 작업이 이미 최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)이므로 취소할 수 없습니다.
Name
404 - Not Found
Description
이 ID를 가진 냉장고 자석 작업이 귀하의 계정에 속하지 않거나, 작업의 단계가 경로와 일치하지 않습니다. ID를 확인하고 작업에 맞게 /prototype 또는 /build를 사용하세요.

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id/stream

냉장고 자석 작업 스트리밍

냉장고 자석 작업의 업데이트를 Server-Sent Events(SSE)로 스트리밍합니다. 경로는 작업의 단계와 일치해야 합니다. 예를 들어 build 작업의 ID로 /prototype/:id/stream에 요청하는 등 일치하지 않는 경우, 스트림은 status_code: 404와 함께 하나의 error 이벤트를 전송하고 종료됩니다.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

매개변수

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

반환값

prototype 또는 build 작업 객체의 스트림입니다. 각 이벤트는 냉장고 자석 작업 조회가 반환하는 것과 동일한 전체 작업 객체를 포함합니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 출력 필드가 여전히 비어 있으며(null, [] 또는 {}), finished_at은 null입니다.

IP 필터링이 작업 결과를 차단하는 경우, 스트림은 그 자리에 get 요청이 반환할 status_code와 함께 하나의 error 이벤트를 전송합니다.

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)

냉장고 자석 작업 목록 조회

하나의 stage에 대한 냉장고 자석 작업을 한 번에 한 페이지씩 반환합니다. 경로에서 stage를 선택합니다. /prototype은 prototype 작업만 반환하고, /build는 build 작업만 반환합니다.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
    "type": "creative-lab-fridge-magnet-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729543210000,
    "started_at": 1729543215000,
    "finished_at": 1729543242000,
    "expires_at": 1729802442000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

경로 매개변수

Name
stage
Type
path
필수
Description
조회할 stage로, prototype 또는 build입니다.

쿼리 매개변수

Name
page_num
Type
integer
기본값 1
Description
반환할 페이지로, 1부터 255까지입니다. 0은 첫 번째 페이지를 반환합니다. 0에서 255를 벗어난 값은 400을 반환합니다.
Name
page_size
Type
integer
기본값 10
Description
페이지당 작업 수로, 최대 100입니다. 101에서 255 사이의 값은 100개의 작업을 반환하며, 0은 기본값을 사용합니다. 0에서 255를 벗어난 값은 400을 반환합니다.
Name
sort_by
Type
string
기본값 -created_at
Description
정렬 순서입니다.
사용 가능한 값:
- -created_at: 최신순
- +created_at: 오래된순

반환값

경로의 stage와 일치하는 prototype 작업 객체 또는 build 작업 객체의 배열입니다.

냉장고 자석 prototype 작업 객체

prototype 작업은 사진으로부터 컬러 콘셉트 이미지를 생성합니다. 이미지를 3D 모델로 변환하려면 해당 작업의 ID를 input_task_id로 build 엔드포인트에 전달하세요.

속성

Example Fridge Magnet Prototype Task Object

{
  "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
  "type": "creative-lab-fridge-magnet-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543210000,
  "started_at": 1729543215000,
  "finished_at": 1729543242000,
  "expires_at": 1729802442000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Name
id
Type
string
Description
작업 ID입니다. 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형으로, 항상 creative-lab-fridge-magnet-prototype입니다.
Name
name
Type
string
Description
작업을 생성할 때 보낸 name이며, 보내지 않았다면 ""입니다.
Name
status
Type
string
Description
작업의 상태입니다.
사용 가능한 값:
- PENDING: 대기열에서 대기 중
- IN_PROGRESS: 결과 생성 중
- SUCCEEDED: 최종 상태이며, 결과 포함
- FAILED: 최종 상태이며, 사유는 task_error에 있음
- CANCELED: 최종 상태이며, 결과 없음
Name
progress
Type
integer
Description
작업 완료 비율로, 0에서 100까지입니다. 작업이 시작되기 전까지는 0이며, 성공하면 100입니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시간으로, 유닉스 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
작업자가 작업을 시작한 시간으로, 유닉스 밀리초 단위입니다. 그 전까지는 null입니다.
Name
finished_at
Type
timestamp
Description
작업이 최종 상태에 도달한 시간으로, 유닉스 밀리초 단위입니다. 그 전까지는 null입니다.
Name
expires_at
Type
timestamp
Description
작업 결과가 만료되는 시간으로, 유닉스 밀리초 단위입니다. finished_at으로부터 3일 후이며, 작업이 완료되기 전까지는 created_at으로부터 3일 후입니다. API 결과를 무기한 보관하는 Enterprise 계정의 경우 약 100년 후입니다. 에셋 보존을 참고하세요.
Name
preceding_tasks
Type
integer
Description
작업이 PENDING 상태일 때 대기열에서의 위치입니다. 1은 다음 차례로 시작됨을 의미합니다. 작업이 대기열을 벗어나면 0이며, 목록 결과에서는 항상 0입니다.
Name
task_error
Type
object
Description
작업이 실패한 이유입니다. status가 FAILED가 아니면 null입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
환불을 반영한 후, 작업에 대해 청구된 크레딧 수입니다. 오류를 반환하는 요청은 청구되지 않습니다. 실패한 작업은 Meshy가 환불하므로 0입니다. 취소는 작업이 PENDING 상태인 동안에만 환불됩니다. Meshy가 청구 내역을 읽을 수 없는 경우, get 또는 stream 응답에는 해당 필드가 생략되고, list 요청은 500을 반환합니다. 이 경우 요청을 재시도하세요.
Name
image_urls
Type
array of strings
Description
콘셉트 이미지의 다운로드 URL입니다. 작업이 성공한 후에는 배열에 URL이 하나 있으며, 그 전까지는 비어 있습니다.

냉장고 자석 빌드 태스크 객체

빌드 태스크는 성공한 프로토타입 태스크로부터 3D 냉장고 자석을 생성합니다. 요청한 형식의 모델 파일 하나를 반환합니다.

속성

Example Fridge Magnet Build Task Object

{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

Name
id
Type
string
Description
태스크 ID입니다. 형식에 의존하지 마세요.
Name
type
Type
string
Description
태스크 유형이며, 항상 creative-lab-fridge-magnet-build입니다.
Name
name
Type
string
Description
태스크를 생성할 때 보낸 name이며, 보내지 않았다면 ""입니다.
Name
status
Type
string
Description
태스크의 상태입니다.
사용 가능한 값:
- PENDING: 대기열에서 대기 중
- IN_PROGRESS: 결과 생성 중
- SUCCEEDED: 최종 상태이며, 결과 포함
- FAILED: 최종 상태이며, 이유는 task_error에 포함
- CANCELED: 최종 상태이며, 결과 없음
Name
progress
Type
integer
Description
작업 완료 비율로, 0에서 100까지입니다. 태스크가 시작되기 전까지는 0이며, 성공하면 100입니다.
Name
created_at
Type
timestamp
Description
태스크가 생성된 시각으로, Unix 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
워커가 태스크를 시작한 시각으로, Unix 밀리초 단위입니다. 시작 전까지는 null입니다.
Name
finished_at
Type
timestamp
Description
태스크가 최종 상태에 도달한 시각으로, Unix 밀리초 단위입니다. 그 전까지는 null입니다.
Name
expires_at
Type
timestamp
Description
태스크 결과가 만료되는 시각으로, Unix 밀리초 단위입니다. finished_at 이후 3일이며, 태스크가 완료되기 전까지는 created_at 이후 3일입니다. API 결과를 무기한 보관하는 Enterprise 계정의 경우 약 100년 뒤입니다. 에셋 보존을 참고하세요.
Name
preceding_tasks
Type
integer
Description
태스크가 PENDING 상태일 때 대기열에서의 위치입니다. 1은 다음 차례로 시작됨을 의미합니다. 태스크가 대기열을 벗어나면 0이며, 목록 결과에서는 항상 0입니다.
Name
task_error
Type
object
Description
태스크가 실패한 이유입니다. status가 FAILED가 아니면 null입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
환불 후 태스크에 청구된 크레딧 수입니다. 오류를 반환하는 요청은 청구되지 않습니다. 실패한 태스크는 Meshy가 환불하므로 0입니다. 취소는 태스크가 PENDING 상태일 때만 환불됩니다. Meshy가 청구 내역을 읽을 수 없는 경우, get 또는 stream 응답에서는 이 필드가 생략되며, list 요청은 500을 반환합니다. 이 경우 요청을 재시도하세요.
Name
model_urls
Type
object
Description
모델 파일의 다운로드 URL로, 요청한 output.format에 대한 항목 하나를 포함합니다. 태스크가 성공하기 전까지는 {}입니다.
- Name
  glb
  Type
  string
  Description
  GLB 파일의 다운로드 URL입니다. output.format이 glb일 때 존재합니다.
- Name
  obj
  Type
  string
  Description
  model.obj, model.mtl, texture.png가 포함된 zip 파일의 다운로드 URL입니다. output.format이 obj일 때 존재합니다.
- Name
  bundle_zip
  Type
  string
  Description
  Meshy가 생성하는 모든 파일이 포함된 zip 파일의 다운로드 URL입니다. output.format이 zip일 때 존재합니다.