Image to 3D Model API 사용법: 완벽 가이드 2026

Image to 3D Model API는 단일 사진을 몇 초 만에 프로덕션에 바로 사용 가능한 3D 모델로 변환합니다. 수동 모델링이 필요하지 않습니다. 모든 에셋을 수동으로 모델링하는 것은 느리고 비용이 많이 들며, 게임 스튜디오, AR 앱, 이커머스 팀에게는 빠르게 출시를 지연시키는 병목 지점이 됩니다. Meshy의 이미지-3D 모델 API는 이러한 마찰을 제거합니다. 이미지를 보내고, 몇 초 만에 3D 모델로 변환한 후, GLB, FBX, OBJ와 같은 형식의 완전한 텍스처가 적용된 메시를 다운로드하세요. 이 가이드는 API 키 생성부터 첫 번째 모델 다운로드까지의 전체 워크플로를 몇 분 안에 실행할 수 있는 복사-붙여넣기 코드와 함께 안내합니다.

Image to 3D Model API란 무엇인가요?

핵심적으로, Image to 3D Model API는 Meshy의 이미지-3D 모델 AI로 구동되는 REST 엔드포인트입니다. 단일 이미지(JPG, JPEG 또는 PNG)를 공개 URL 또는 base64 문자열로 보내면, API는 GLB, FBX, OBJ, USDZ, STL, 3MF와 같은 표준 형식의 텍스처가 적용된 3D 모델(형상 및 기본 색상 텍스처 포함)을 반환합니다. 선택적 추가 기능으로는 PBR 맵, 최대 4K 텍스처, 다중 각도 미리보기 썸네일이 있습니다.

최신 Meshy 6 모델로 구동되는 이 API를 사용하면 토폴로지와 폴리곤 수를 구성하고, 포즈 모드를 설정하며, 텍스트 프롬프트나 참조 이미지로 텍스처링을 안내할 수 있습니다. 게임, AR/VR, 3D 프린팅 및 제품 시각화를 위한 에셋 생성에 이상적입니다.

Image to 3D API를 사용하려면 무엇이 필요하나요?

이 가이드를 따라하는 데 많은 것이 필요하지 않습니다. 다음만 준비하세요.

• Meshy 계정 — 계정이 없다면 무료로 가입하세요. 1단계에서 대시보드에서 API 키를 생성합니다.

• API 키 — 모든 요청을 인증하는 데 사용됩니다. 키를 생성하는 과정을 안내하며, 크레딧을 소모하지 않고 따라할 수 있는 무료 테스트 모드 키를 사용할 수 있습니다.

• 입력 이미지 — 공개적으로 접근 가능한 URL(또는 base64로 인코딩된)에 호스팅된 선명한 .jpg, .jpeg 또는 .png 파일입니다. 깔끔한 배경과 명확하게 보이는 피사체가 가장 좋은 결과를 제공합니다.

• HTTP 요청을 보낼 방법 — curl(아래 예제에서 사용), Postman 또는 선호하는 언어의 모든 HTTP 라이브러리입니다. REST API 및 JSON에 대한 기본적인 친숙함이 도움이 되지만 필수는 아닙니다.

이것으로 끝입니다. 3D 모델링 경험이 필요하지 않습니다. 시작해 봅시다.

API를 사용하여 이미지를 3D 모델로 변환하는 방법 (단계별 가이드)

1단계: API 설정 구성

빌드를 시작하는 데 필요한 모든 것은 API 설정 페이지에 있습니다. 이것은 Meshy API의 제어 센터이며, 세 가지 주요 섹션이 있습니다.

• API 키 — 요청을 인증하는 키를 생성하고 관리합니다.

• 웹훅 — 작업이 완료되면 자동으로 알림을 받습니다.

• 사용량 — 남은 크레딧 잔액과 API 소비량을 실시간으로 추적합니다.

각각을 살펴보겠습니다.

API 키 얻기

요청을 보내기 전에, 안전하게 인증할 API 키가 필요합니다. API 설정 페이지에서 API 키 생성을 클릭하세요. 모든 키는 msy-<임의-문자열> 형식을 따릅니다.

팁: 생성되면 API 키를 안전한 곳(예: 비밀번호 관리자 또는 환경 변수)에 저장하세요. 비밀번호처럼 취급하고, 소스 제어에 커밋하거나 클라이언트 측 코드에 노출하지 마십시오.

테스트 모드 API 키

개발 및 테스트 중에는 테스트 모드 API 키를 사용하여 크레딧을 소모하지 않고 API를 탐색할 수 있습니다.

msy_dummy_api_key_for_test_mode_12345678

이 특수 키는 다음과 같은 특징이 있습니다.

• 모든 Meshy API 엔드포인트에 요청하는 데 사용할 수 있습니다.

• 이 키를 사용해도 크레딧이 소모되지 않습니다.

• 모든 유효한 요청은 입력 매개변수와 관계없이 동일한 샘플 작업 결과를 반환합니다.

• 응답 데이터 구조는 프로덕션 API와 정확히 일치합니다.

따라서 실제 API 키로 전환하기 전에 통합을 테스트하는 데 완벽합니다.

웹훅 설정 (선택 사항)

3D 모델을 생성하는 데는 시간이 걸리므로, 작업이 완료되었는지 확인하기 위해 API를 반복적으로 폴링하는 대신 Meshy가 작업이 완료되는 즉시 알리도록 할 수 있습니다. 이것이 바로 웹훅의 용도입니다.

설정 페이지의 웹훅 섹션에서 Meshy가 이벤트 알림을 보낼 엔드포인트 URL을 추가하세요. 작업 상태가 변경되면(예: 완료 또는 실패), Meshy는 페이로드에 작업 세부 정보와 함께 HTTP POST 요청을 URL로 보냅니다.

팁: 웹훅은 프로덕션에 권장되는 방법입니다. 불필요한 API 호출을 줄이고 애플리케이션이 결과에 실시간으로 반응할 수 있게 합니다. 빠른 테스트의 경우 폴링도 잘 작동합니다. 웹훅 코드를 로컬에서 테스트하려면 smee.io와 같은 서비스의 프록시 URL을 가리키세요.

코드 없이 시도해보기 — API 플레이그라운드 (선택 사항)

이미 API 키가 있나요? 코드를 작성하기 전에 브라우저에서 직접 실제 Image to 3D 작업을 실행할 수 있습니다.

meshy.ai/api-playground를 열고 왼쪽 패널에서 Image to 3D를 선택한 후 세 가지를 입력하세요.

1. Authorization — API 키(msy-xxxxxxxxxx)를 붙여넣습니다.

2. Image — 컴퓨터에서 .jpg, .jpeg 또는 .png 파일을 업로드합니다.

3. Send를 누릅니다.

플레이그라운드는 작업을 제출하고 자동으로 결과를 폴링합니다. 완료되면 코드 없이 브라우저에서 바로 3D 모델 미리보기와 다운로드 링크를 볼 수 있습니다.

프로 팁: 오른쪽의 원시 요청/응답 패널은 API가 보내고 반환하는 내용을 정확히 보여줍니다. 콘텐츠를 직접 복사할 수 있습니다. 응답에서 task_id를 가져오고, 작업이 완료되면 model_urls를 가져오세요. 다음 단계에서 둘 다 사용합니다.

2단계: Image to 3D 작업 제출

API 키가 준비되었으면, 단일 POST 요청으로 작업을 시작합니다.

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

다음과 같은 응답을 받게 됩니다.

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

이 result 값이 바로 task_id입니다. 저장해 두세요. 다음 단계에서 진행 상황을 확인하고 모델을 검색하는 데 필요합니다.

선택 사항: 작업이 완료되면 자동으로 알림을 받으려면 JSON 본문에 webhook_url 필드를 추가하세요(예: "webhook_url": "https://yourapp.com/webhooks/meshy"). 작동 방식은 3단계, 옵션 B를 참조하세요.

3단계: 결과 얻기

작업이 즉시 완료되지는 않습니다. Meshy는 백그라운드에서 처리합니다. 결과를 얻는 두 가지 방법이 있습니다.

옵션 A: 상태 폴링 (가장 간단함)

status가 SUCCEEDED로 변경될 때까지 5초마다 GET 요청을 보냅니다.

curl https://api.meshy.ai/openapi/v1/image-to-3d/{task_id} \
  -H "Authorization: Bearer $MESHY_API_KEY"

응답은 다음과 같습니다.

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

알아두면 좋은 몇 가지 필드:

• model_urls 는 생성된 모든 형식에 대한 다운로드 링크를 보유합니다. 기본적으로 glb, fbx, obj, usdz, stl 및 mtl(obj와 쌍을 이루는 재질 파일)이 포함됩니다.

• model_url 은 GLB 링크의 바로 가기입니다. GLB만 필요한 경우 편리합니다.

• consumed_credits 는 작업에 사용된 크레딧 수를 표시합니다(실패한 작업의 경우 크레딧이 환불되므로 0입니다).

• thumbnail_url 은 항상 존재하며 정면 썸네일을 가리킵니다.

• thumbnail_urls 는 multi_view_thumbnails: true인 경우에만 나타나며 정면, 오른쪽, 후면 및 왼쪽 뷰를 포함합니다.

• alpha_thumbnail_url 은 alpha_thumbnail: true인 경우에만 나타나며 투명 배경 썸네일을 보유합니다.

가능한 status 값: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

옵션 B: 웹훅 (프로덕션에 권장)

2단계에서 webhook_url을 설정한 경우, Meshy는 완료된 작업 객체를 자동으로 URL에 POST합니다. 폴링이 필요 없습니다.

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 어느 것을 사용해야 하나요? 폴링은 프로토타이핑 및 일회성 작업에 적합합니다. 프로덕션에서는 웹훅을 사용하세요. 더 안정적이고 API 호출을 절약할 수 있습니다.

4단계: 3D 모델 다운로드

status가 SUCCEEDED가 되면 model_urls에서 다운로드 URL을 가져와 필요한 형식을 다운로드합니다.

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

-o model.glb 플래그는 파일을 현재 작업 디렉토리에 해당 이름으로 저장합니다. 전체 경로(예: -o /path/to/model.glb)를 사용하여 다른 곳에 저장할 수 있습니다.

기본적으로 모든 작업은 GLB, FBX, OBJ, USDZ, STL 및 MTL(OBJ용 재질 파일)을 반환합니다. 3MF는 옵트인 방식입니다. target_formats를 통해 명시적으로 요청한 경우에만 얻을 수 있습니다(아래 매개변수 표 참조).

⚠️ 링크는 3일 후에 만료됩니다(엔터프라이즈 요금제는 영구 링크 제공). 모델을 즉시 다운로드하여 저장하세요. 만료 후에는 링크가 작동하지 않으며 작업을 다시 실행해야 합니다.

이 모델을 DCC 도구에서 사용할 준비가 되셨나요? Bridge to Blender 가이드를 참조하세요. Meshy는 Unity, Unreal, Maya 등을 위한 브릿지도 제공합니다.

최상의 이미지-3D 결과를 얻는 방법은 무엇인가요?

• 단일하고 명확하게 보이는 피사체를 사용하세요. 하나의 주요 객체를 중앙에 배치하고 프레임에 완전히 담으면 AI가 가장 깔끔한 참조를 얻을 수 있습니다. 복잡한 장면, 심한 크롭, 극단적인 각도는 피하세요.

• 깔끔하고 정리된 배경을 선호하세요. 단색 또는 단순한 배경은 모델이 피사체를 주변 환경과 분리하는 데 도움이 됩니다.

• 균일하고 확산된 조명을 사용하세요. 거친 그림자와 강한 하이라이트는 생성된 텍스처에 오해의 소지가 있는 디테일을 각인시킬 수 있습니다.

• 고해상도의 선명한 이미지로 시작하세요. 입력에 더 많은 디테일이 있으면 출력에도 더 많은 디테일이 생깁니다. 흐릿하거나 저해상도 입력은 더 부드러운 모델을 생성합니다.

Image to 3D API와 함께 사용할 수 있는 프로그래밍 언어는 무엇인가요?

HTTP 요청을 보낼 수 있는 모든 언어가 가능합니다. JSON으로 POST를 보내고 GET으로 폴링합니다. 일반적인 옵션은 다음과 같습니다.

• Python — requests 또는 httpx 라이브러리 사용

• JavaScript / TypeScript — fetch(내장) 또는 axios 사용

• Go — 표준 라이브러리의 net/http 사용

• cURL — 터미널에서 빠른 테스트에 좋습니다.

API 플레이그라운드에서 네 가지 모두에 대한 복사 가능한 코드 샘플을 찾을 수도 있습니다.

Image to 3D 작업 비용은 얼마인가요?

비용은 모델 버전과 텍스처 생성 여부에 따라 다릅니다. 기본 설정(meshy-6 및 텍스처링)은 작업당 30 크레딧입니다.

실패한 작업은 자동으로 환불됩니다. consumed_credits는 0을 반환합니다. 최신 요금은 항상 가격 페이지를 확인하세요.

Image to 3D API는 어떤 매개변수를 허용하나요?

다음 매개변수와 함께 /openapi/v1/image-to-3d로 POST를 보내세요. 필수 (다음 중 하나):

선택 사항:

Image to 3D API의 다음 단계

이제 완전한 워크플로를 갖추었습니다. API 키 생성, 이미지 제출, 폴링 또는 웹훅을 통한 결과 확인, 모델 다운로드입니다. 동일한 네 단계는 빠른 프로토타입에서 수천 개의 이미지를 3D 에셋으로 자동 변환하는 프로덕션 파이프라인으로 확장됩니다. API 설정 페이지에서 키를 가져와 오늘 첫 번째 모델을 출시하세요. 사진 대신 프롬프트로 시작하는 것을 선호하시나요? Text to 3D Model API를 사용하세요.

자주 묻는 질문

API를 통해 이미지를 3D 모델로 변환하려면 어떻게 해야 하나요?

image_url과 API 키와 함께 /openapi/v1/image-to-3d로 POST 요청을 보낸 다음, status가 SUCCEEDED가 될 때까지 작업을 폴링(또는 웹훅 사용)합니다. 응답은 생성된 모델의 다운로드 링크를 반환합니다. 전체 4단계 흐름(키, 제출, 검색, 다운로드)은 위의 단계별 가이드에 설명되어 있습니다.

API는 어떤 출력 형식(STL, GLB, OBJ)을 지원하나요?

모든 작업은 기본적으로 GLB, FBX, OBJ, USDZ, STL 및 MTL을 반환하며, 3MF는 target_formats를 통해 요청 시 사용할 수 있습니다. GLB는 웹 및 AR에 가장 적합하고, FBX와 OBJ는 DCC 도구 및 게임 엔진에, USDZ는 iOS AR에, STL은 3D 프린팅에 적합합니다.

어떤 이미지 형식을 업로드할 수 있나요?

Image to 3D API는 최대 100MB의 JPG, JPEG 및 PNG 이미지를 지원합니다. 이는 Meshy Workspace UI의 20MB 제한보다 큽니다. 가장 정확한 결과를 얻으려면 투명하거나 깔끔한 흰색 배경의 PNG를 사용하세요. 이렇게 하면 API가 피사체를 분리하고 더 높은 품질의 3D 모델을 생성하는 데 도움이 됩니다.

API에서 텍스처가 적용된 3D 모델을 얻을 수 있나요?

네. 텍스처링은 기본적으로 활성화되어 있습니다("should_texture": true). PBR 맵(메탈릭, 러프니스, 노멀)을 추가하려면 "enable_pbr": true로 설정하세요. meshy-6/latest에서는 이미션 맵도 포함됩니다. 4K 기본 색상 텍스처의 경우 "hd_texture": true로 설정하세요(meshy-6/latest에서만 지원되며 PBR 맵은 2K로 유지됨). texture_prompt 또는 texture_image_url로 텍스처 스타일을 조정할 수도 있습니다.

3D 프린팅(STL)에 바로 사용할 수 있는 3D 모델을 생성할 수 있나요?

네. STL은 기본적으로 생성되므로, 이미지-3D STL 변환에는 추가 매개변수가 필요하지 않습니다. 작업이 완료되면 model_urls.stl을 가져오기만 하면 됩니다. STL은 슬라이서가 기대하는 표준 형식이므로 이미지-3D 프린트 워크플로가 간단해집니다. STL만 필요한 경우 "target_formats": ["stl"]로 설정하여 다른 형식을 건너뛰고 생성 시간을 단축하세요.

어떤 요금제에 API 액세스가 포함되나요?

API 액세스는 Pro, Studio 및 Enterprise 요금제에서 사용할 수 있습니다. Pro 이상의 기능입니다. 무료 Starter 요금제에는 API 액세스가 포함되지 않습니다. 자세한 내용은 가격 페이지를 참조하세요.

다운로드 링크는 얼마나 유효한가요?

다운로드 링크는 Pro 및 Studio 요금제에서 3일 동안 유효합니다. 엔터프라이즈 고객은 영구 링크를 받습니다. 파일을 즉시 저장하세요. 만료된 링크는 복구할 수 없으며 작업을 다시 실행해야 합니다.

동시에 여러 작업을 실행할 수 있나요?

네, 동시 요청이 지원됩니다. 429 Too Many Requests 오류가 발생하면 계정의 속도 제한에 도달한 것입니다. 지수 백오프를 구현하고 재시도하세요. 요금제의 제한 사항은 속도 제한 페이지를 참조하세요.

작업이 FAILED로 표시됩니다. 어떻게 해야 하나요?

task_error.message에서 원인을 확인하세요. 일반적인 원인은 다음과 같습니다.

문제가 지속되면 Meshy 지원팀에 문의하세요.