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

> URL: https://help.meshy.ai/ko/articles/16102100-meshy-api-webhooks-vs-polling-when-results-are-ready
> Language: ko
> Last updated: 2026-09-09T10:16:14Z

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

`"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 영업팀에 문의하세요.

## FAQ

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

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

### 2. 폴링과 웹훅 중 무엇을 사용해야 하나요?

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

### 3. 서버가 동일한 웹훅을 두 번 수신하면 어떻게 해야 하나요?

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

### 4. 웹훅이 전혀 도착하지 않습니다 — 어떻게 해야 하나요?

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

### 5. 실패했거나 만족스럽지 않은 생성을 API를 통해 직접 재시도할 수 있나요?

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

### 6. status가 SUCCEEDED가 된 후 결과를 다운로드할 수 있는 기간은 얼마나 되나요?

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