Meshy API 웹훅 vs 폴링: 결과가 준비되었는지 확인하는 방법

Meshy API 생성 작업(Text to 3D, Image to 3D, 리깅 등)은 비동기식으로 실행됩니다. 작업을 제출한 후 결과를 가져오기 전에 작업이 완료되었는지 확인해야 합니다. 이 문서에서는 작업 수명 주기와 작업 완료 시점을 파악하는 두 가지 지원 방식인 폴링과 웹훅, 그리고 가장 흔한 "모델 검색 오류" 문제를 피하는 방법을 설명합니다.

모든 생성 작업은 몇 가지 상태를 거치며, 작업 객체의 status 필드에 반환됩니다:

• PENDING — 작업이 대기열에 등록되었지만 아직 처리가 시작되지 않았습니다.

• IN_PROGRESS — 작업이 현재 처리 중입니다. progress 필드(0-100)는 작업이 진행됨에 따라 증가합니다.

• SUCCEEDED — 작업이 성공적으로 완료되었으며 progress는 100입니다. 이제 응답에서 결과 URL(모델 파일, 텍스처, 미리보기)을 사용할 수 있습니다.

• FAILED — 작업을 완료할 수 없었습니다. 실패한 작업의 크레딧은 자동으로 환불됩니다.

• CANCELED — 작업이 완료되기 전에 취소되었습니다.

API 연동 시 가장 중요한 규칙은 작업의 status가 SUCCEEDED가 될 때까지 결과 URL을 가져오거나 사용하지 않는 것입니다. 작업이 아직 PENDING 또는 IN_PROGRESS 상태일 때 결과를 읽는 것이 "모델 검색 오류" 보고의 가장 흔한 원인입니다.

폴링이란 작업 ID에 대해 "작업 가져오기" 엔드포인트를 반복적으로 호출하여 종료 상태(SUCCEEDED, FAILED 또는 CANCELED)에 도달할 때까지 확인하는 것을 의미합니다. 간단한 폴링 루프는 다음과 같습니다:

• 생성 요청을 제출하고 반환된 작업 id를 저장합니다.

• 해당 "작업 조회" 엔드포인트(예: Text to 3D 또는 Image to 3D의 task-by-id 엔드포인트)를 일정 간격으로 호출합니다. 일반적으로 몇 초 간격이 적당합니다.

• 각 응답에서 status 필드를 확인합니다. PENDING 또는 IN_PROGRESS 상태인 동안은 폴링을 계속합니다.

• status가 SUCCEEDED(결과 URL을 읽음), FAILED 또는 CANCELED가 되는 즉시 폴링을 중단합니다.

• 클라이언트에 적절한 타임아웃/최대 시도 횟수 가드를 추가하여 멈춘 작업이 영원히 폴링되지 않도록 합니다.

폴링은 간단하며 스크립트, 배치 작업, 소규모 연동에 적합합니다. 대량 트래픽이나 지연 시간에 민감한 연동에는 웹훅이 일반적으로 더 적합합니다.

"다 되었나요?"라고 반복적으로 묻는 대신, 작업이 완료되는 순간 Meshy가 서버에 알리도록 요청할 수 있습니다. 웹훅을 사용하려면:

• Meshy가 접근할 수 있는 웹훅(콜백) URL을 구성합니다. 엔드포인트에 따라 일반적으로 계정/API 설정 수준에서 설정하거나 생성 요청의 파라미터로 전달합니다.

• 엔드포인트가 HTTPS를 통해 공개적으로 접근 가능하고 빠르게 응답하는지 확인합니다(즉시 2xx 상태를 반환한 후 페이로드를 비동기적으로 처리).

• 작업이 종료 상태에 도달하면 Meshy가 작업 id와 최종 status를 포함하는 페이로드를 엔드포인트로 전송합니다.

• 수신 시 웹훅 본문만 믿지 말고 API를 통해 id로 전체 작업 세부 정보를 조회하여 권위 있고 최신인 결과를 갖고 있는지 확인합니다.

웹훅은 불필요한 API 호출을 줄이고 거의 즉각적인 알림을 제공하지만, 웹훅 전송이 누락되거나 지연될 수 있는 작업(예: 사용자 측의 일시적 네트워크 문제)을 위해 주기적인 폴링 대체 수단도 유지해야 합니다.

폴링을 사용하든 웹훅을 사용하든, 결과 처리 코드는 멱등적이어야 합니다. 즉, 동일한 작업에 대해 부작용 없이 여러 번 실행해도 안전해야 합니다. 그 이유는 다음과 같습니다:

• 동일한 작업에 대해 웹훅이 두 번 이상 전송될 수 있습니다(전송 측의 재시도, 네트워크 중복 등).

• 폴링 루프와 웹훅 핸들러가 모두 실행 중이라면, 둘 다 동일한 완료된 작업을 처리하려 할 수 있습니다.

멱등성을 유지하려면 처리 로직을 작업 id를 기준으로 구성하세요. 예를 들어, 다시 수행하기 전에 해당 id에 대한 결과를 이미 저장/다운로드했는지 확인하고, "처리 완료로 표시"를 자체 데이터베이스에서 단일 원자적 단계로 만드세요.

"status": "SUCCEEDED"와 "progress": 100이 포함된 응답만이 결과 페이로드(모델 URL, 텍스처, 썸네일)가 완전하며 안전하게 사용할 수 있음을 보장하는 유일한 신호입니다. 구체적으로 코드에서는 다음을 수행하세요:

• result/모델 URL 필드에서 무엇이든 읽기 전에 status === "SUCCEEDED"인지 확인합니다.

• progress만 믿지 마세요. 작업이 완전히 마무리되기 전에 progress가 일시적으로 높은 값을 표시할 수 있으므로 항상 status도 함께 확인하세요.

• SUCCEEDED가 되면 즉시 결과 파일을 다운로드하세요. 생성된 에셋은 Meshy 서버에 제한된 기간 동안만 보관되며, 그 이후에는 URL이 더 이상 작동하지 않습니다.

대부분의 "모델을 검색할 수 없습니다" 보고는 다음 원인 중 하나로 추적됩니다:

• 너무 이른 호출. status가 SUCCEEDED가 되기 전에 결과 URL을 호출하거나 모델 필드를 읽는 경우. 이것이 압도적으로 가장 빈번한 원인입니다.

• 만료된 에셋. SUCCEEDED 후 너무 오래 다운로드를 기다리는 경우 — 해당 작업 유형의 보관 기간이 지나면 결과 URL이 작동하지 않습니다.

• 오래되었거나 잘못된 작업 ID 사용 — 예를 들어 이전의 관련 없는 요청의 ID를 재사용하는 경우.

• FAILED를 일시적 상태로 취급하고, 재제출하는 대신 이미 실패한 작업을 계속 폴링하는 경우.

• 서버와 Meshy 간의 네트워크/타임아웃 문제가 생성 문제로 잘못 해석되는 경우.

생성 결과가 기대에 미치지 못하거나 요청이 완전히 실패한 경우, 다음 사항을 유의하세요:

• Meshy API는 현재 기존 작업을 그 자리에서 재시도하는 기능을 지원하지 않습니다. 다시 시도하려면 새 생성 요청을 제출해야 하며, 이는 정상적으로 크레딧을 소비합니다.

• API 호출 시 일시적인 네트워크 오류(타임아웃, 5xx 응답)가 발생하면, 재제출 전에 짧은 지수 백오프를 적용하는 것이 합리적입니다.

• 폴링 자체의 경우, 일시적인 네트워크 오류가 발생하면 "작업 가져오기" 호출을 재시도하되, 단일 폴링 실패를 생성 실패로 간주하지 마세요. 성공적인 응답을 받은 경우에만 status 필드를 신뢰하세요.

• 생성에 대한 내장 재시도 기능이 필요한 경우, 엔터프라이즈 플랜 옵션에 대해 Meshy 영업팀에 문의하세요.

이는 거의 항상 작업이 완료되기 전에 코드가 결과를 읽으려 하기 때문에 발생합니다. 모델 URL을 검색하기 전에 항상 status가 SUCCEEDED(그리고 progress가 100)인지 확인하세요.

폴링은 설정이 더 간단하며 소규모 또는 일회성 스크립트에 적합합니다. 웹훅은 불필요한 반복 요청을 피하고 작업 완료 시 즉시 알림을 제공하므로, 많은 동시 작업이 있는 프로덕션 연동에 더 적합합니다.

멱등적으로 처리하세요 — 작업 id를 이미 처리한 내용과 대조하고, 이미 처리되었다면 재처리를 건너뜁니다.

id로 직접 작업을 폴링하는 방식으로 대체하세요. 또한 엔드포인트가 HTTPS를 통해 공개적으로 접근 가능하고 빠르게 2xx 응답을 반환하는지 확인하세요. 느리거나 접근할 수 없는 엔드포인트는 전송 문제를 일으킬 수 있습니다.

현재는 불가능합니다 — 새 생성 요청을 제출해야 하며, 이는 정상적으로 크레딧을 소비합니다. 내장 재시도 지원이 필요한 경우 엔터프라이즈 옵션에 대해 영업팀에 문의하세요.

결과 파일은 작업 완료 후 Meshy 서버에 제한된 기간 동안만 보관되므로, 기다리지 말고 작업이 성공하는 즉시 자체 스토리지에 출력물을 다운로드하세요.

• API를 사용해 생성 결과에서 모델을 검색할 때 지속적으로 오류가 발생하는 이유는 무엇인가요?