Meshy API 웹훅 vs 폴링: 결과가 준비되는 시점

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

모든 생성 작업은 소수의 상태를 거치며, 이는 작업 객체의 status 필드에 반환됩니다:

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

• IN_PROGRESS — 작업이 활발히 처리되고 있습니다. progress 필드(0-100)는 작업이 완료됨에 따라 증가합니다.

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

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

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

API를 통합할 때 가장 중요한 단일 규칙은 다음과 같습니다: 작업의 status가 SUCCEEDED가 되기 전에는 결과 URL을 가져오거나 사용하려고 시도하지 마세요. 작업이 아직 PENDING 또는 IN_PROGRESS인 상태에서 결과를 읽는 것이 "모델을 가져오는 중 오류 발생" 보고의 가장 흔한 원인입니다.

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

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

• 해당 "retrieve task" 엔드포인트(예: Text to 3D 또는 Image to 3D의 작업 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만 신뢰하지 말고 항상 status도 함께 확인하세요. 작업이 완전히 마무리되기 전에 progress가 잠시 높은 값을 표시할 수 있기 때문입니다.

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

대부분의 "모델을 가져올 수 없습니다"라는 신고는 다음 원인 중 하나로 귀결됩니다:

• 너무 일찍 가져오기. status가 SUCCEEDED가 되기 전에 결과 URL을 호출하거나 모델 필드를 읽는 경우입니다. 이는 단연코 가장 빈번한 원인입니다.

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

• 오래되었거나 잘못된 작업 ID 사용 — 예를 들어 이전의 무관한 요청에서 가져온 ID를 재사용하는 경우입니다.

• FAILED를 일시적 상태로 간주하고 다시 제출하지 않은 채 이미 실패한 작업을 계속 폴링하는 경우.

• 서버와 Meshy 사이의 네트워크/타임아웃 문제를 생성 문제로 오해하는 경우.

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

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

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

• 폴링 자체의 경우 일시적인 네트워크 오류 시 "get task" 호출을 재시도하되, 단일 폴링 실패를 생성 실패로 간주하지 마세요. 성공적인 응답을 받은 후에만 status 필드를 신뢰해야 합니다.

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

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

폴링은 설정이 더 간단하며 처리량이 적거나 일회성 스크립트에 적합합니다. 웹훅은 동시 작업이 많은 프로덕션 통합에 더 적합합니다. 불필요한 반복 요청을 피하고 작업이 완료되는 즉시 알림을 받을 수 있기 때문입니다.

멱등하게 처리하세요 — 작업 id를 이미 처리한 항목과 대조하고, 이미 처리된 경우 다시 처리를 건너뛰세요.

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

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

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