lowpoly는 2026. 10. 30.에 지원 종료됩니다. 요청 오류를 피하려면 해당 날짜 전에 모델을 전환하세요. 모든 지원 중단 보기

Creative Lab 키링 API

사진을 두 단계에 걸쳐 컬러 릴리프가 적용된 3D 프린팅용 키링으로 변환합니다. 프로토타입 작업은 사진으로부터 색상이 적용된 콘셉트 이미지를 생성합니다. 빌드 작업은 해당 이미지를 릴리프 3D 모델로 변환하며, 프로토타입 작업의 ID를 input_task_id로 사용합니다.

  • POST /openapi/creative-lab/keychain/v1/prototype
  • POST /openapi/creative-lab/keychain/v1/build
POST/openapi/creative-lab/keychain/v1/prototype

Keychain 프로토타입 작업 생성

사진에서 색상이 입혀진 콘셉트 이미지 하나를 생성합니다. 3D 모델을 빌드하려면 이 작업의 ID를 build 엔드포인트에 input_task_id로 전달하세요. 작업의 필드에 대해서는 The Keychain prototype task object를 참조하세요.

Request

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

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Prototype example
Start with a source photo, then generate the prototype image used by the keychain build stage.
Source photo used as the Creative Lab Keychain input
Prototype input
Creative Lab Keychain 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_text를 사용하세요.

  • Name
    name_text
    Type
    string
    Description

    반려동물이나 사람의 이름처럼 키체인에 추가할 이름으로, 최대 10자까지 입력할 수 있습니다. Meshy는 바이트가 아니라 글자 수를 세므로, 한국어·중국어·일본어 이름 10자도 입력할 수 있습니다. 이름이 더 길면 400을 반환합니다. 이름이 없는 키체인을 원하면 비워 두세요.

    이름은 돌출되거나 음각된 텍스트가 아니라, 키체인 표면에 평평한 색상 디테일로 표시됩니다.

    Meshy는 앞뒤 공백을 제거하고 보이지 않는 서식 문자를 제거합니다. 프로토타입 작업 객체는 그 결과를 name_text로 반환하므로, 빌드 비용을 지불하기 전에 텍스트를 확인할 수 있습니다.

    Meshy는 프로토타입 단계에서 이름을 추가합니다. build는 이를 그대로 유지하며, build 엔드포인트로 전송된 name_text는 무시합니다.

    텍스트가 순수 ASCII가 아닌 경우, 요청 본문을 Content-Type: application/json; charset=utf-8로 UTF-8로 전송하세요. Windows PowerShell의 Invoke-RestMethod와 같은 일부 HTTP 클라이언트는 기본적으로 본문을 ISO-8859-1로 인코딩합니다. 이렇게 되면 요청이 Meshy에 도달하기 전에 라틴 문자가 아닌 모든 문자가 ?로 바뀌며, Meshy는 이를 의도한 이름과 구분할 수 없습니다.

  • Name
    remove_background
    Type
    boolean
    기본값 false
    Description

    프로토타입 이미지에서 배경을 제거할지 여부입니다. true로 설정하면 메달리온 전체를 유지한 투명 RGBA PNG를 반환하여 어떤 배경 위에도 배치할 수 있습니다. build도 배경이 제거된 이미지에서 시작합니다. Meshy가 배경을 제거할 수 없는 경우, 배경이 있는 이미지를 반환하며 작업은 그대로 성공합니다.

    build의 remove_background 옵션은 별개입니다.

반환 값

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

실패 모드

  • Name
    400 - Bad Request
    Description

    요청을 실행할 수 없습니다. 예를 들어:

    • image_url이 누락되었습니다.
    • 이미지가 JPG, JPEG, PNG, 또는 WebP 파일이 아닙니다.
    • 이미지가 너무 작거나, 20MB를 초과하거나, 최대 픽셀 수를 초과합니다.
    • Meshy가 이미지를 다운로드할 수 없습니다. 예를 들어 URL이 404를 반환하거나 시간이 초과된 경우입니다.
    • data URI가 유효한 base64가 아닙니다.
    • name_text가 10자를 초과합니다. Meshy는 이를 줄이는 대신 거부하며, 요청에 대한 비용을 청구하지 않습니다.
    • 이미지 또는 name_text가 NSFW로 표시되었습니다.

    오류 메시지에 어떤 문제가 발견되었는지 표시됩니다. 요청을 수정한 후 다시 보내세요.

  • Name
    401 - Unauthorized
    Description

    API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.

  • Name
    402 - Payment Required
    Description

    다음 중 하나에 해당합니다:

    • 계정에 크레딧이 부족합니다.
    • API 키, 작업 공간, 또는 멤버가 크레딧 한도에 도달했습니다.
    • 계정이 무료 플랜을 사용 중입니다.

    크레딧과 플랜을 확인한 후 다시 시도하세요.

  • Name
    403 - Forbidden
    Description

    팀에서 IP 필터링이 켜져 있고, Meshy가 이미지를 제3자 지적 재산권 문제로 표시했습니다. 사용 권한이 있는 이미지를 보내세요. Meshy는 이미지에 대해서만 지적 재산권을 확인하며, name_text는 확인하지 않습니다.

  • Name
    429 - Too Many Requests
    Description

    다음 한도 중 하나에 도달했습니다:

    • 속도 제한에서 허용하는 것보다 더 많은 요청을 보냈습니다. 몇 초 기다린 후 다시 시도하세요. 속도 제한을 참조하세요.
    • 대기 중이거나 실행 중인 작업이 너무 많습니다. 일부가 완료될 때까지 기다린 후 다시 시도하세요.
    • 크레딧이 남아 있지 않은 무제한 플랜에서, 크레딧 없이 실행할 수 있는 작업 수에 도달했습니다. 작업이 완료되길 기다리거나 크레딧을 추가하세요.
  • Name
    500 - Internal Server Error
    Description

    Meshy에서 서버 오류가 발생했습니다. 예를 들어 이미지에 대한 지적 재산권 검사를 실행할 수 없었던 경우입니다. Meshy는 작업을 생성하지 않으며, 청구된 크레딧이 있다면 환불합니다. 요청을 다시 시도하세요.

POST/openapi/creative-lab/keychain/v1/build

키링 빌드 태스크 생성

성공한 프로토타입 태스크로부터 3D 프린팅 가능한 키링을 생성합니다. Meshy는 프로토타입의 콘셉트 이미지를 뎁스맵 릴리프로 변환하고, 선택한 포맷의 모델 파일 하나를 반환합니다. 태스크의 필드에 대해서는 키링 빌드 태스크 객체를 참조하세요.

Request

POST
/openapi/creative-lab/keychain/v1/build
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Build example
The build task converts the selected prototype image into a 3D-printable keychain model.
Creative Lab Keychain build model preview
Build model preview

파라미터

  • Name
    input_task_id
    Type
    string
    필수
    Description

    빌드할 프로토타입 태스크의 ID입니다. POST /openapi/creative-lab/keychain/v1/prototype로 본인 계정이 생성했으며, 상태가 SUCCEEDED인 태스크여야 합니다.

    API를 통해 생성된 본인의 키링 프로토타입 태스크가 아닌 ID는 웹 앱에서 만든 프로토타입을 포함하여 404를 반환합니다.

  • Name
    name
    Type
    string
    Description

    태스크의 이름으로, 최대 100자까지 가능합니다. 태스크의 name 필드에 그대로 반환됩니다. 더 긴 이름은 400을 반환합니다.

options

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

  • Name
    badge_shape
    Type
    string
    기본값 circle
    Description

    Meshy가 피사체로부터 윤곽선을 추출하지 못할 때 사용되는 키링의 외곽선입니다. remove_background가 false일 때, 또는 피사체의 윤곽선을 찾을 수 없을 때 Meshy가 이를 사용합니다.

    사용 가능한 값:

    • circle
    • rounded-rect
    • hexagon
    • shield
    • star
  • Name
    size_mm
    Type
    number
    기본값 40
    Description

    키링의 경계 사각형의 가장자리 길이로, 밀리미터 단위이며 최대 400까지 가능합니다. 0은 기본값을 사용합니다.

  • Name
    relief_height_mm
    Type
    number
    기본값 2.2
    Description

    베이스 위로 솟은 릴리프의 최대 높이로, 밀리미터 단위이며 0에서 20까지입니다.

  • Name
    relief_offset_mm
    Type
    number
    기본값 0
    Description

    릴리프를 얼마나 낮출지를 밀리미터 단위로 지정하며, 0에서 20까지입니다. Meshy는 이 값을 베이스까지 릴리프의 모든 높이에서 뺍니다.

  • Name
    base_thickness_mm
    Type
    number
    기본값 0.1
    Description

    릴리프 뒤에 있는 평평한 베이스 판의 두께로, 밀리미터 단위이며 0에서 20까지입니다.

  • Name
    has_closed_back
    Type
    boolean
    기본값 true
    Description

    키링의 뒷면을 닫을지 여부입니다. false는 뒷면을 쉘 형태로 열어 둡니다.

  • 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픽셀 뎁스맵으로부터 지오메트리를 생성하므로, 더 정밀한 메시는 디테일을 추가하지 않고 면만 늘립니다. 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/keychain/v1/(prototype|build)/:id

키링 작업 가져오기

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

필드에 대해서는 키링 프로토타입 작업 객체와 키링 빌드 작업 객체를 참고하세요.

Request

GET
/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

매개변수

  • Name
    id
    Type
    path
    Description

    생성 응답에서 받은 작업 ID입니다.

반환값

경로의 단계에 맞는 프로토타입 작업 객체 또는 빌드 작업 객체입니다.

실패 모드

  • Name
    400 - Bad Request
    Description

    id가 유효한 작업 ID가 아닙니다. 생성 응답에서 받은 result ID를 전송하세요.

  • Name
    403 - Forbidden
    Description

    팀에서 IP 필터링이 활성화되어 있고, Meshy가 프로토타입 작업의 이미지를 제3자 지적 재산권으로 표시했습니다. 빌드 작업과 Enterprise 요금제 팀에는 이 오류가 발생하지 않습니다. 사용 권한이 있는 이미지로 프로토타입 작업을 생성하세요.

  • Name
    404 - Not Found
    Description

    이 ID를 가진 키링 작업이 계정에 속해 있지 않거나, 작업의 단계가 경로와 일치하지 않습니다. ID를 확인하고 작업에 맞게 /prototype 또는 /build를 사용하세요.

  • Name
    500 - Internal Server Error
    Description

    Meshy가 지적 재산권 검사를 실행하지 못했습니다. 요청을 재시도하세요.

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

키링 작업 삭제

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

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

Request

DELETE
/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -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/keychain/v1/(prototype|build)/:id/stream

Keychain 작업 스트리밍

Keychain 작업의 업데이트를 Server-Sent Events(SSE)로 스트리밍합니다. 경로는 작업의 단계와 일치해야 합니다. 예를 들어 build 작업의 ID로 /prototype/:id/stream을 호출하는 등 일치하지 않는 경우, 스트림은 status_code: 404가 포함된 error 이벤트를 한 번 전송하고 종료됩니다.

Request

GET
/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream
curl -N https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/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": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

매개변수

  • Name
    id
    Type
    path
    Description

    생성 응답에서 제공된 작업 ID입니다.

반환값

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

IP Filtering이 작업 결과를 차단하는 경우, 스트림은 그 자리에 get 요청이 반환할 status_code를 포함한 error 이벤트를 한 번 전송합니다.

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

키링 작업 목록 조회

한 단계(stage)의 키링 작업을 한 번에 한 페이지씩 반환합니다. 경로가 단계를 선택합니다. /prototype은 프로토타입 작업만 반환하고, /build는 빌드 작업만 반환합니다.

Request

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

경로 매개변수

  • Name
    stage
    Type
    path
    필수
    Description

    조회할 단계로, 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: 오래된 순

반환 값

경로의 단계에 맞는 프로토타입 작업 객체 또는 빌드 작업 객체의 배열입니다.

키링 prototype 작업 객체

prototype 작업은 사진으로부터 색상이 적용된 컨셉 이미지를 생성합니다. 이미지를 3D 모델로 변환하려면 작업의 ID를 빌드 엔드포인트에 input_task_id로 전달하세요.

속성

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "name_text": "Luna",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "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-keychain-prototype입니다.

  • Name
    name
    Type
    string
    Description

    작업을 생성할 때 보낸 name입니다. 보내지 않은 경우 ""입니다.

  • Name
    name_text
    Type
    string
    Description

    공백을 제거하고 보이지 않는 서식 문자를 제거한 후 Meshy가 키링에 추가한 이름입니다. name_text를 보내지 않은 경우 생략됩니다. HTTP 클라이언트가 텍스트를 올바르게 인코딩했는지 확인하려면, 보낸 값과 비교하세요.

  • 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 또는 스트림 응답에서는 이 필드가 생략되며, 목록 요청은 500을 반환합니다. 이 경우 요청을 재시도하세요.

  • Name
    image_urls
    Type
    array of strings
    Description

    컨셉 이미지의 다운로드 URL입니다. 작업이 성공한 후에는 배열에 URL이 하나 들어 있으며, 그전까지는 비어 있습니다.

키링 빌드 태스크 객체

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

속성

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}
  • Name
    id
    Type
    string
    Description

    태스크 ID입니다. 이 형식에 의존하지 마세요.

  • Name
    type
    Type
    string
    Description

    태스크 유형으로, 항상 creative-lab-keychain-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

    태스크가 생성된 시간으로, 유닉스 밀리초 단위입니다.

  • 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 또는 스트림 응답에서는 이 필드가 생략되고, 목록 요청은 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일 때 존재합니다.