lowpoly는 2026. 10. 30.에 지원 종료됩니다. 3D 생성 모델 meshy-7은 2026. 12. 31.에 지원 종료됩니다. 텍스처 모델로는 계속 사용할 수 있습니다. 요청 오류를 피하려면 해당 날짜 전에 모델을 전환하세요. 모든 지원 중단 보기

작업 라이프사이클

작업이 요청부터 결과까지 어떻게 진행되는지, 일반적으로 얼마나 걸리는지, 그리고 코드가 얼마나 기다려야 하는지 알아봅니다.


작업 실행 방식

생성 요청은 작업이 실행될 때까지 기다리지 않고 작업 ID를 반환합니다. 그런 다음 작업은 백그라운드에서 실행되며, 다음 세 가지 방법 중 하나로 진행 상황을 확인할 수 있습니다: GET 엔드포인트를 폴링하거나, 스트림 엔드포인트를 열거나, webhook을 수신하는 방법입니다.

생성 요청은 PENDING 상태로 작업을 시작합니다. 워커가 작업을 가져가면 IN_PROGRESS로 전환되며, 대부분의 시간을 이 상태에서 보냅니다. 작업은 SUCCEEDED 또는 FAILED로 종료되며, 최종 상태는 이후 변경되지 않습니다.
생성 요청
PENDING
대기열에서 대기 중
IN_PROGRESS
결과 생성 중
SUCCEEDED
결과 다운로드
FAILED
크레딧 환불됨

작업은 각 단계를 created_at, started_at, finished_at 필드에 기록합니다.

다음 표는 각 상태에서 코드가 수행해야 할 작업을 보여줍니다.

상태코드가 수행해야 할 작업
PENDING계속 대기합니다.
IN_PROGRESSprogress(완료된 작업의 비율, 0에서 100까지)를 추적합니다.
SUCCEEDED결과를 다운로드합니다. Meshy는 파일을 제한된 기간 동안 보관합니다. 에셋 보존을 참고하세요.
FAILEDtask_error를 읽고 입력을 수정하거나 새 작업을 생성합니다. 오류를 참고하세요.
CANCELED더 이상 기다리지 않습니다. 작업은 결과를 생성하지 않습니다. Creative Lab 작업만 이 상태를 사용합니다.

SUCCEEDED, FAILED, CANCELED는 최종 상태입니다. 작업이 이 중 하나에 도달한 후에는 상태가 다시는 변경되지 않습니다.

코드 관점에서는 다음과 같이 진행됩니다:

작업을 생성한 다음, 완료될 때까지 폴링합니다.
  1. 요청: POST/image-to-3d

  2. 응답: 202{ "result": "<task_id>" }작업 생성됨

  3. 몇 초마다 반복
    1. 요청: GET/image-to-3d/<task_id>

    2. 응답: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5

  4. 요청: GET/image-to-3d/<task_id>

  5. 응답: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }

앱이 대기를 중단해도 작업은 계속 실행됩니다. 동일한 작업 ID로 나중에 GET 요청을 보내세요.

처리 시간

다음 표는 2026년 9월 프로덕션 API 트래픽에서의 중앙값 시간을 보여줍니다.

시간은 작업 생성부터 최종 상태까지를 기준으로 합니다. 작업은 보통 PENDING 상태로 몇 초밖에 머무르지 않으므로, 거의 모든 시간이 처리 시간입니다. 대기열이 혼잡할 때는 작업이 시작되기 전까지 더 오래 기다릴 수 있으며, 우선순위가 더 높은 플랜의 작업은 보통 더 빨리 시작됩니다.

2분 미만의 시간은 초(s) 단위로, 더 긴 시간은 분(min) 단위로 표시됩니다. "지원되지 않음"은 해당 모델에서 API가 해당 옵션을 제공하지 않는다는 의미입니다.

3D 생성

API구성meshy-7.1 (latest)meshy-6meshy-6-litemeshy-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초가 더 걸립니다.
  • Ultra 지오메트리(geometry_resolution: "2k" 또는 "4k")를 사용하면 최대 1분이 더 걸립니다.
  • 동일한 설정에서 더 복잡한 입력 이미지는 시간이 더 오래 걸립니다.

텍스처링

API텍스처 해상도일반적인 시간
텍스트로 3D (Refine)2K 또는 4K80초
8K3.5분
리텍스처2K55초
4K90초
8K2.5분

이미지 생성

APInano-banananano-banana-2nano-banana-proGPT Image 모델
텍스트로 이미지20초15초25초20~35초
이미지로 이미지40초20초30초20~40초

리깅 및 애니메이션

API구성일반적인 시간
자동 리깅자동 리깅40초
애니메이션요청당15초
텍스트로 모션prime mode15초
swift mode10초

후처리

API일반적인 시간
리메시2분
UV 언래핑35초
변환7초
크기 조정15초

3D 프린팅

API구성일반적인 시간
프린팅 가능성 분석메시 검사만1초
메시 및 박막 검사10초
멀티 컬러요청당30초
프린팅 가능성 복구메시 복구만10초
박막 검사, 벽 유지20초
박막 검사, 벽 두껍게 처리100초
Auto Split단색 파츠70초
텍스처가 있는 파츠(keep_texture: true)170초

v2에서는 프린팅 가능성 복구와 프린팅 가능성 분석이 항상 박막 검사를 실행합니다. v1에서는 프린터 유형이나 출력 크기를 전송했을 때만 실행됩니다.


얼마나 기다려야 할까

코드가 대기를 중단하더라도 작업은 계속 실행됩니다. 요청이 timeout되거나, 연결이 끊어지거나, 스트림이 닫혀도 작업이 실패하거나 취소되는 것은 아닙니다.

  • 대기를 중단하기 전에 작업의 created_at을 기준으로 최소 60분을 기다리세요. 더 일찍 중단하면 나중에 성공하는 작업을 놓칠 수 있습니다. 이는 주로 혼잡한 시간대에 발생합니다.
  • 작업 ID를 보관하세요. 언제든지 작업을 다시 조회할 수 있습니다. 60분이 지나도 여전히 최종 상태가 아니라면 나중에 다시 확인하세요. 계속 그 상태라면 지원팀에 문의하세요.
  • FAILED만이 작업 실패를 의미합니다. Meshy는 실패한 작업을 자동으로 환불합니다.

코드에서 다음 값을 사용하세요:

설정권장 값
생성 요청(POST) timeout60초
model_url 파일이 100MB를 초과하는 생성 요청(POST) timeout120초. Meshy는 응답하기 전에 파일을 다운로드합니다.
상태 요청(GET) timeout30초
폴링 간격Retry-After 헤더 값, 없을 경우 5초. 폴링은 속도 제한에 포함됩니다.
실패한 상태 요청(timeout, 429, 또는 5xx)다음 폴링에서 다시 시도하세요. 작업이 실패했다는 의미는 아닙니다.
작업당 전체 대기 시간created_at 기준 최소 60분. 스트림을 재연결할 때 이 카운트를 다시 시작하지 마세요.
스트림스트림은 작업이 완료되기 전에 닫힐 수 있습니다. 최종 상태 없이 닫힌 경우, 재연결하거나 폴링 방식으로 전환하세요.

한 번에 많은 작업을 처리할 때는 각각을 폴링하는 대신 webhooks를 사용하세요. 작업의 최종 이벤트가 일반적인 소요 시간의 약 두 배가 지나도 도착하지 않으면, 해당 작업의 GET 엔드포인트에서 작업을 조회하세요.