Creative Lab — 키캡 API

Meshy가 키캡 디자인 이미지로 변환할 소스 사진입니다. 현재 .jpg, .jpeg, .png, .webp 형식을 지원합니다.

형식은 이미지 데이터를 디코딩하여 감지되며, URL의 파일 확장자로 감지되지 않습니다 — 확장자가 없는 URL이나 리디렉션되는 URL이라도 바이트가 지원되는 형식으로 디코딩되기만 하면 정상적으로 동작합니다. HTTP 리디렉션은 따라갑니다. EXIF 방향 정보는 정규화되므로, 회전된 휴대폰 사진도 보이는 그대로 사용됩니다.

제한 사항: 각 변이 최소 32픽셀 이상, 전체 최대 178,956,970픽셀, 다운로드 후 최대 20,000,000바이트입니다. Data URI의 경우 이 제한은 디코딩된 바이트에 적용되므로, 소스 파일 자체는 그 크기까지 허용될 수 있습니다 — base64 텍스트는 약 3분의 1 정도 더 커지지만, 이는 요청 본문에 관한 문제일 뿐 이 제한과는 무관합니다. Data URI는 image/* 콘텐츠 타입과 ;base64를 명시해야 합니다.

이미지를 제공하는 방법은 두 가지입니다:

• 공개적으로 접근 가능한 URL: 공개 인터넷에서 접근 가능한 URL입니다.
• Data URI: 이미지의 base64 인코딩된 data URI입니다. data URI 예시: data:image/jpeg;base64,<your base64-encoded image data>.

표시 목적의 선택적 작업 이름입니다. 최대 100자입니다.

true로 설정하면 image_urls에 반환되는 디스플레이 렌더는 배경이 제거된 투명 RGBA PNG가 되어, 원하는 배경 위에 합성할 수 있습니다.

이는 디스플레이 렌더에만 적용됩니다. 빌드 엔드포인트가 사용하는 candidate에는 영향을 주지 않으므로, 3D 결과는 어느 쪽이든 동일합니다.

요청이 허용되지 않았습니다. 일반적인 원인:

• 파라미터 누락: image_url은 필수입니다.
• 잘못된 이미지 형식: 제공된 image_url이 지원되는 형식(.jpg, .jpeg, .png, .webp)이 아닙니다.
• 이미지 크기 범위 초과: 이미지가 너무 작거나, 최대 파일 크기를 초과하거나, 최대 픽셀 수를 초과합니다.
• 접근할 수 없는 URL: image_url을 다운로드할 수 없습니다(404 또는 timeout).
• 잘못된 Data URI: base64 문자열의 형식이 올바르지 않습니다.
• 콘텐츠 플래그 처리됨: 입력 이미지가 NSFW moderation에 의해 플래그 처리되었습니다.

인증에 실패했습니다. API 키를 확인해 주세요.

계정이 무료 플랜을 사용 중이거나(작업 생성에는 유료 플랜이 필요합니다) 크레딧이 부족합니다.

입력 이미지가 지적 재산권 moderation에 의해 플래그 처리되었습니다.

속도 제한을 초과했습니다.

예기치 않은 서버 측 오류가 발생했습니다 — 예를 들어 콘텐츠 moderation 서비스를 사용할 수 없었거나, 입력 이미지를 스테이징하는 데 실패했거나, 작업을 생성할 수 없었던 경우입니다. 이 경우 작업이 생성되지 않으므로 재시도해도 안전합니다.

동일한 OpenAPI 엔드포인트를 통해 생성된 프로토타입 태스크의 태스크 ID입니다. 프로토타입은 동일한 Meshy 계정에 의해 생성되어야 하며, SUCCEEDED 상태에 도달해야 하고, 최소 하나 이상의 후보를 생성했어야 합니다.

웹앱을 통해 생성된 프로토타입 태스크는 허용되지 않습니다 — 빌드 엔드포인트는 POST /openapi/creative-lab/keycap/v1/prototype에 의해 생성된 프로토타입 태스크만 받아들이며, 그 외의 출처는 모두 404로 거부합니다.

빌드할 후보로, 성공한 프로토타입 태스크의 candidate_ids 배열에서 가져옵니다. 해당 태스크에 속해야 하며, 그 외의 값은 400으로 거부됩니다.

표시 목적의 선택적 태스크 이름입니다. 최대 100자입니다.

빌드할 키캡 베이스입니다. 현재 사용 가능한 유일한 값은 cherry-mx-1x1-r1 — 표준 Cherry MX 프로파일 1u 키캡입니다. 3~5개의 추가적인 주류 표준 사이즈가 계획되어 있으며, 커스텀 사이즈는 지원되지 않습니다.

조각된 헤드의 목표 크기로, 밀리미터 단위입니다: 가장 긴 치수가 이 값으로 스케일링됩니다. 범위: [10, 40]. 대략 32.9를 초과하는 값은 헤드가 베이스의 보호 풋프린트 한계 내에 들어가도록 축소될 수 있으므로, 전달되는 최장 치수가 요청한 값보다 작아질 수 있습니다. 적용된 값은 현재 태스크 객체에 반영되지 않습니다 — 실제로 받은 크기를 확인해야 하는 경우, 다운로드한 모델에서 keycap-head 메시의 바운딩 박스를 측정하세요.

헤드가 베이스에 안착되기 전에 적용되는 수직 오프셋으로, 밀리미터 단위입니다. 범위: [-5, 5].

요청이 허용되지 않았습니다. 일반적인 원인:

• 파라미터 누락: input_task_id와 candidate_id가 필요합니다.
• 유효하지 않은 UUID: input_task_id가 유효한 UUID가 아닙니다.
• 부모가 성공하지 않음: 참조된 프로토타입 태스크가 아직 SUCCEEDED에 도달하지 않았습니다.
• 후보 없음: 프로토타입 태스크는 성공했지만 후보를 생성하지 못했습니다.
• 알 수 없는 후보: candidate_id가 입력 태스크의 후보 중 하나가 아닙니다.
• 옵션 범위 초과: options 필드 중 하나가 허용된 범위나 열거값 집합을 벗어났습니다.

인증에 실패했습니다. API 키를 확인해 주세요.

계정이 무료 플랜을 사용 중이거나(태스크 생성에는 유료 플랜이 필요합니다) 크레딧이 부족합니다.

참조된 프로토타입 태스크가 존재하지 않거나, 다른 사용자에게 속해 있거나, 웹앱을 통해 생성되었습니다(API 모드 프로토타입 태스크만 빌드로 연결될 수 있습니다).

속도 제한을 초과했습니다.

예기치 않은 서버 측 오류가 발생했습니다 — 예를 들어 콘텐츠 moderation 서비스를 사용할 수 없었거나, 입력 이미지를 스테이징하는 데 실패했거나, 태스크를 생성할 수 없었습니다. 이 경우 태스크가 생성되지 않으므로 재시도해도 안전합니다.

조회할 키캡 작업의 고유 식별자입니다.

취소할 키캡 작업의 고유 식별자입니다.

작업이 이미 최종 상태이므로 취소할 수 없습니다.

작업이 존재하지 않거나, 다른 사용자에게 속해 있거나, 해당 단계가 URL 경로와 일치하지 않습니다.

취소 처리 중 예기치 않은 서버 측 오류가 발생했습니다. 작업이 취소되었을 수도 있고 아닐 수도 있으므로 재시도하기 전에 다시 조회하여 확인하세요.

스트리밍할 키캡 작업의 고유 식별자입니다.

prototype 또는 build 중 하나입니다. 이 컬렉션은 URL과 단계가 일치하는 작업만 반환합니다 — /prototype을 조회하면 빌드 작업이 절대 반환되지 않으며, 그 반대도 마찬가지입니다.

페이지네이션을 위한 페이지 번호입니다.

페이지 크기 제한입니다. 최대 허용 값은 100개 항목입니다.

정렬 기준 필드입니다. 사용 가능한 값:

• +created_at: 생성 시간 오름차순으로 정렬합니다.
• -created_at: 생성 시간 내림차순으로 정렬합니다.

작업의 고유 식별자입니다. 구현 세부사항으로 작업 id에 k-정렬 가능한 UUID를 사용하지만, id의 형식에 대해 어떠한 가정도 해서는 안 됩니다.

작업의 유형입니다. 값은 creative-lab-keycap-prototype입니다.

작업 생성 시 지정된 작업 이름입니다. 이름이 제공되지 않은 경우 빈 문자열입니다.

작업의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.

작업의 progress입니다. 작업이 아직 시작되지 않은 경우 이 속성은 0이 됩니다. 작업이 성공하면 100이 됩니다.

작업이 생성된 시각의 타임스탬프이며, 밀리초 단위입니다.

작업이 시작된 시각의 타임스탬프이며, 밀리초 단위입니다. 작업이 아직 시작되지 않은 경우 이 속성은 0이 됩니다.

작업이 완료된 시각의 타임스탬프이며, 밀리초 단위입니다. 작업이 아직 완료되지 않은 경우 이 속성은 0이 됩니다.

작업 결과가 만료되는 시각의 타임스탬프이며, 밀리초 단위입니다.

선행 작업의 수입니다.

실패한 작업에 대한 오류 세부정보입니다. task_error 객체 전체 참조는 오류를 참고하세요.

이 작업에서 소비된 크레딧 수입니다. SUCCEEDED에 도달한 작업은 해당 단계에 대한 전체 금액이 청구됩니다. 생성조차 되지 않은 작업(요청 시점의 4xx, moderation 거부 포함)은 전혀 청구되지 않습니다. FAILED에 도달한 작업은 0을 반환합니다 — 비동기 moderation 차단을 포함하여 청구액이 환불됩니다. DELETE를 통한 취소는 작업이 아직 PENDING인 동안에만 환불되며, 이미 IN_PROGRESS 상태인 작업은 작업이 이미 소비되었기 때문에 청구된 상태로 유지됩니다.

완성된 키캡 디자인 렌더링의 다운로드 가능한 URL입니다 — 후보가 완성된 키캡으로 어떻게 보이는지를 나타냅니다. 항목이 하나만 있으며, image_urls[i]는 candidate_ids[i]에 대응합니다. 작업이 SUCCEEDED에 도달하기 전까지는 비어 있습니다. 이 URL은 표시 전용이며, 빌드 엔드포인트는 이 URL이 아니라 candidate_ids를 사용합니다. model_urls와 동일한 URL 수명 주기를 가집니다: 서명되어 있고, Authorization 헤더가 없으며, expires_at까지 유효하고, 작업을 다시 읽어도 안정적으로 유지됩니다.

image_urls와 병렬로 대응하는 불투명한 후보 식별자입니다. 선택한 디자인에 해당하는 항목을 빌드 요청의 candidate_id로 전달하세요. 이 id들의 형식에 대해 어떠한 가정도 하지 마세요.

태스크의 고유 식별자입니다.

태스크의 유형입니다. 값은 creative-lab-keycap-build입니다.

태스크 생성 시 제공된 태스크 이름입니다. 이름이 제공되지 않은 경우 빈 문자열입니다.

태스크의 상태입니다. 가능한 값은 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.

태스크의 진행률입니다. 태스크가 아직 시작되지 않은 경우 이 속성은 0입니다. 태스크가 성공하면 100이 됩니다.

태스크가 생성된 시각의 타임스탬프이며, 밀리초 단위입니다.

태스크가 시작된 시각의 타임스탬프이며, 밀리초 단위입니다.

태스크가 종료된 시각의 타임스탬프이며, 밀리초 단위입니다.

태스크 결과가 만료되는 시각의 타임스탬프이며, 밀리초 단위입니다.

선행 태스크의 개수입니다. 상태가 PENDING일 때만 의미가 있습니다.

실패한 태스크에 대한 오류 세부 정보입니다. task_error 객체의 전체 레퍼런스는 오류를 참조하세요.

이 태스크에서 소비된 크레딧 수입니다. SUCCEEDED에 도달한 태스크는 해당 단계에 대한 전체 금액이 청구됩니다. 아예 생성되지 않은 태스크(요청 시점의 4xx, moderation 거부 포함)는 전혀 청구되지 않습니다. FAILED에 도달한 태스크는 0을 반환하며, 이는 비동기 moderation 차단을 포함해 요금이 환불됨을 의미합니다. DELETE를 통한 취소는 태스크가 아직 PENDING 상태일 때만 환불되며, 이미 IN_PROGRESS인 태스크는 작업이 이미 소비되었기 때문에 계속 청구된 상태로 유지됩니다.

생성된 모델 아티팩트를 다운로드할 수 있는 URL입니다. GLB와 OBJ 번들 모두 실제 세계 밀리미터 단위 스케일, Y-up으로 익스포트되며, keycap의 정면은 +Z 방향을 향합니다. 메시는 keycap-head와 keycap-base로 명명되며, 베이스가 패턴 채우기로 대체되는 경우 스템 캐비티를 위한 세 번째 메시 keycap-base-interior도 함께 존재합니다. 메시가 정확히 두 개라고 가정하지 마세요.

이는 서명된 URL이므로 Authorization 헤더 없이 가져와야 합니다. 이 URL은 expires_at까지 유효하며, 이는 finished_at으로부터 3일 후이고, 그 기간 내에 태스크를 다시 읽으면 새로 서명된 URL이 아니라 동일한 URL이 반환됩니다. 만료되기 전에 파일을 직접 다운로드하여 저장하세요. 만료된 링크를 새로고침할 방법은 없습니다.

종류별로 키가 지정된 중간 프로세스 이미지를 다운로드할 수 있는 URL입니다. model_urls와 동일한 URL 라이프사이클을 가지며, 서명되어 있고 Authorization 헤더가 필요 없으며, expires_at까지 유효하고, 태스크를 다시 읽어도 값이 안정적으로 유지됩니다. 현재 생성되는 종류는 다음과 같습니다:

• head_design — 빌드가 소비한, 선택된 candidate의 디자인 이미지입니다(항상 존재).
• composite — 선택된 candidate의 완성된 keycap 디스플레이 렌더입니다(사용 가능한 경우 존재).
• base_canvas — 채색된 keycap 베이스 캔버스입니다(사용 가능한 경우 존재).

이 키 집합은 열려 있는 것으로 간주하세요. 이후 호환성을 깨지 않으면서 새로운 종류가 추가될 수 있습니다.