작업 생명 주기
작업이 요청에서 결과까지 어떻게 진행되는지, 보통 얼마나 걸리는지, 그리고 코드에서 얼마나 기다려야 하는지 알아봅니다.
작업 실행 방식
생성 요청은 작업이 실행되기를 기다리지 않고 작업 ID를 반환합니다. 그런 다음 작업은 백그라운드에서 실행되며, GET 엔드포인트를 폴링하거나, 스트림 엔드포인트를 열거나, webhook을 수신하는 세 가지 방법 중 하나로 이를 추적할 수 있습니다.
PENDING 상태로 작업을 시작합니다. 작업자가 이를 가져가면 IN_PROGRESS로 전환되며, 작업 대부분의 시간을 이 상태에서 보냅니다. 작업은 SUCCEEDED 또는 FAILED로 종료되며, 최종 상태는 이후 변경되지 않습니다.PENDINGIN_PROGRESSSUCCEEDEDFAILED작업은 각 단계를 created_at, started_at, finished_at 필드에 기록합니다.
다음 표는 각 상태에서 코드가 수행해야 할 작업을 보여줍니다.
| 상태 | 코드가 수행해야 할 작업 |
|---|---|
PENDING | 계속 대기합니다. |
IN_PROGRESS | progress(0에서 100까지 완료된 작업의 백분율)를 추적합니다. |
SUCCEEDED | 결과를 다운로드합니다. Meshy는 파일을 제한된 기간 동안 보관합니다. 에셋 보존을 참조하세요. |
FAILED | task_error를 확인한 후 입력을 수정하거나 새 작업을 생성합니다. 오류를 참조하세요. |
CANCELED | 대기를 중단합니다. 작업은 결과를 생성하지 않습니다. Creative Lab 작업에서만 이 상태를 사용합니다. |
SUCCEEDED, FAILED, CANCELED는 최종 상태입니다. 작업이 이 중 하나에 도달하면 상태는 다시 변경되지 않습니다.
코드에서 보면 다음과 같습니다:
요청: POST/image-to-3d
응답: 202{ "result": "<task_id>" }작업 생성됨
- 몇 초마다 반복
요청: GET/image-to-3d/<task_id>
응답: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5
요청: GET/image-to-3d/<task_id>
응답: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }
GET 하세요.처리 시간
다음 표는 2026년 9월 프로덕션 API 트래픽의 중앙값 시간을 보여줍니다.
시간은 작업 생성부터 최종 상태까지 측정됩니다. 작업은 보통 PENDING 상태에 몇 초만 머무르기 때문에 이 시간의 거의 전부가 처리 시간입니다. 대기열이 혼잡할 때는 작업이 시작되기 전에 더 오래 기다릴 수 있으며, 더 높은 우선순위를 가진 플랜의 작업은 보통 더 빨리 시작됩니다.
2분 미만의 시간은 초(s) 단위로, 더 긴 시간은 분(min) 단위로 표시됩니다. 지원되지 않음은 해당 모델에서 API가 해당 옵션을 제공하지 않는다는 의미입니다.
이는 일반적인 시간이며, 보장된 완료 시간이 아닙니다. 혼잡한 시간대에는 일부 작업이 더 오래 걸리더라도 성공합니다. Meshy의 상태를 확인하려면 상태 페이지를 참조하세요. 코드에서 이 시간을 timeout 값으로 사용하지 마세요. timeout 값에 대해서는 대기해야 하는 시간을 참조하세요.
3D 생성
| API | 구성 | meshy-7.1(latest) | meshy-6 | meshy-6-lite | meshy-t2 |
|---|---|---|---|---|---|
| 텍스트로 3D(Preview) | 메시만 | 75초 | 90초 | 45초 | 10초 |
| 이미지로 3D | 메시만 | 75초 | 90초 | 40초 | 4초 |
| 2K 텍스처가 있는 메시 | 2분 | 3분 | 75초 | 60초 | |
| 4K 텍스처가 있는 메시 | 2.5분 | 3.5분 | 지원되지 않음 | 80초 | |
| 8K 텍스처가 있는 메시 | 3.5분 | 4분 | 지원되지 않음 | 2.5분 | |
| 멀티 이미지로 3D | 메시만 | 65초 | 2분 | 30초 | 지원되지 않음 |
| 2K 텍스처가 있는 메시 | 2.5분 | 3.5분 | 85초 | 지원되지 않음 | |
| 4K 텍스처가 있는 메시 | 3분 | 4분 | 지원되지 않음 | 지원되지 않음 | |
| 8K 텍스처가 있는 메시 | 3.5분 | 4.5분 | 지원되지 않음 | 지원되지 않음 |
이미지로 3D 및 멀티 이미지로 3D의 경우 "메시만"은 should_texture: false를 의미합니다. 다음 옵션과 입력은 시간을 변경시킵니다:
- PBR 맵(
enable_pbr)은 30초에서 60초가 추가됩니다. - 울트라 지오메트리(
geometry_resolution: "2k"또는"4k")는 최대 1분이 추가됩니다. - 동일한 설정에서, 더 복잡한 입력 이미지는 더 오래 걸립니다.
텍스처링
| API | 텍스처 해상도 | 일반적인 시간 |
|---|---|---|
| 텍스트로 3D(Refine) | 2K 또는 4K | 80초 |
| 8K | 3.5분 | |
| 리텍스처 | 2K | 55초 |
| 4K | 90초 | |
| 8K | 2.5분 |
이미지 생성
| API | nano-banana | nano-banana-2 | nano-banana-pro | GPT Image 모델 |
|---|---|---|---|---|
| 텍스트로 이미지 | 20초 | 15초 | 25초 | 20~35초 |
| 이미지로 이미지 | 40초 | 20초 | 30초 | 20~40초 |
리깅 및 애니메이션
후처리
3D 프린팅
| API | 구성 | 일반적인 시간 |
|---|---|---|
| 프린팅 가능성 분석 | 메시 검사만 | 1초 |
| 메시 및 얇은 벽 검사 | 10초 | |
| 멀티 컬러 | 요청당 | 30초 |
| 프린팅 가능성 복구 | 메시 복구만 | 10초 |
| 얇은 벽 검사, 벽 유지 | 20초 | |
| 얇은 벽 검사, 벽 두껍게 처리 | 100초 | |
| Auto Split | 요청당 | 70초 |
v2에서는 프린팅 가능성 복구와 프린팅 가능성 분석이 항상 얇은 벽 검사를 실행합니다. v1에서는 프린터 유형이나 프린트 크기를 보낼 때 실행됩니다.
대기해야 하는 시간
코드가 대기를 중단해도 작업은 계속 실행됩니다. 요청이 timeout되거나, 연결이 끊어지거나, 스트림이 닫혀도 작업은 실패하지 않으며 취소되지도 않습니다.
- 대기를 중단하기 전에 작업의
created_at을 기준으로 최소 60분을 기다리세요. 더 일찍 중단하면 나중에 성공하는 작업을 놓칠 수 있습니다. 이는 주로 혼잡한 시간대에 발생합니다. - 작업 ID를 보관하세요. 언제든지 작업을 다시 조회할 수 있습니다. 60분이 지나도 여전히 최종 상태가 아니라면 나중에 다시 확인하세요. 계속 그런 상태라면 지원팀에 문의하세요.
- 작업이 실패했다는 것은 오직
FAILED만을 의미합니다. Meshy는 실패한 작업에 대해 자동으로 환불합니다.
코드에서 다음 값을 사용하세요:
| 설정 | 권장 값 |
|---|---|
생성 요청(POST) timeout | 60초 |
100MB를 초과하는 model_url 파일이 있는 생성 요청(POST) timeout | 120초. Meshy는 응답하기 전에 파일을 다운로드합니다. |
상태 요청(GET) timeout | 30초 |
| 폴링 간격 | Retry-After 헤더 값, 없을 경우 5초. 폴링은 속도 제한에 포함됩니다. |
실패한 상태 요청(timeout, 429, 또는 5xx) | 다음 폴링 시 다시 시도하세요. 작업이 실패했다는 의미는 아닙니다. |
| 작업당 전체 대기 시간 | created_at 기준 최소 60분. 스트림을 재연결할 때 이 카운트를 다시 시작하지 마세요. |
| 스트림 | 스트림은 작업이 완료되기 전에 닫힐 수 있습니다. 최종 상태 없이 닫히면 재연결하거나 폴링으로 전환하세요. |
한 번에 많은 작업을 처리할 때는 각각을 폴링하는 대신 webhooks를 사용하세요. 작업의 최종 이벤트가 일반적인 시간의 약 두 배가 지나도 도착하지 않으면 해당 작업의 GET 엔드포인트에서 작업을 조회하세요.