Wandy3D API
코드, 엔진, AI 에이전트에서 3D 모델을 만들어 보세요
사진 한 장, 여러 각도의 사진 또는 문장 하나를 보내면 텍스처가 입혀진 3D 모델을 받아요. 그다음 내보내고, 3D 프린팅하고, 쿼드로 리메시하고, 리깅하거나 게임 엔진용으로 패키징할 수 있어요. 스튜디오와 같은 파이프라인을 일반 HTTPS로 사용해요.
모델당 US$0.09부터 (Wandy 1) · Wandy 2 US$0.18
US$2.00 무료 체험 — 첫 API 키로 Wandy 2 모델 약 11개 또는 Wandy 1 모델 약 22개를 만들 수 있어요.
- 만료 없는 선불 잔액 · 구독 없음
- Bearer 키 인증
- 키당 분당 60회 요청
- HTTPS 기반 REST와 JSON
# 1. Start a generation from a photo (Wandy 2)curl -s -X POST "https://api.wandy3d.com/generate/cloud/ultra" \ -H "Authorization: Bearer $WANDY3D_API_KEY" \ -F "file=@photo.jpg"# → {"task_id": "<task_id>", "status": "queued", "billing": {"cost_usd": "<price>", "balance_usd": "<balance>"}, …}빠른 시작
사진에서 GLB 파일까지 4단계면 돼요.
- 1
키 만들기
API 플랫폼의 API 키에서 키를 만든 다음 API 잔액을 충전하세요. 키는 한 번만 표시되니
WANDY3D_API_KEY같은 환경 변수에 보관하세요. - 2
생성 시작
POST
/generate/cloud/ultra사진 한 장을 multipart 필드
file로 보내세요. 응답에task_id가 담겨 와요. - 3
작업 상태 확인
GET
/task/{task_id}/statusstatus가done이 될 때까지 몇 초마다 확인하세요. 완료되면 응답에model_id가 담겨 와요. - 4
다운로드
GET
/model/{model_id}/export?format=glbGLB는 짧은 시간만 유효한 링크로 바로 응답해요. 다른 형식은 먼저 변환되니, 준비될 때까지 같은 URL을 확인하세요.
# 1. Start a generation from a photo (Wandy 2)curl -s -X POST "https://api.wandy3d.com/generate/cloud/ultra" \ -H "Authorization: Bearer $WANDY3D_API_KEY" \ -F "file=@photo.jpg"# → {"task_id": "<task_id>", "status": "queued", "billing": {"cost_usd": "<price>", "balance_usd": "<balance>"}, …}# 2. Poll until "status" is "done"curl -s "https://api.wandy3d.com/task/<task_id>/status" \ -H "Authorization: Bearer $WANDY3D_API_KEY"# → {"status": "done", "model_id": "<model_id>", …}# 3. Get a download link, then download the GLBcurl -s "https://api.wandy3d.com/model/<model_id>/export?format=glb" \ -H "Authorization: Bearer $WANDY3D_API_KEY"# → {"status": "ready", "url": "<download_url>", "filename": "<name>.glb", …}curl -L -o model.glb "<download_url>"키와 한도
모든 요청은 Authorization 헤더에 키를 담아 보내요.
Authorization: Bearer hg_live_…키는 비밀로 유지하세요
키는 내 계정으로 동작하며 API 잔액을 사용해요. 서버, 스크립트, CI에서만 사용하고 웹 페이지나 모바일 앱에는 절대 넣지 마세요. 유출된 키는 API 플랫폼에서 폐기하면 즉시 작동이 멈춰요.
요청 한도
키당 분당 60회 요청. 한도를 넘으면 429 응답과 함께 기다려야 할 초 수를 나타내는 retry_after가 와요.
최대 키 10개
앱이나 기기마다 키를 하나씩 쓰면 다른 키에 영향 없이 하나만 폐기할 수 있어요.
오류
오류는 JSON으로 와요. 대부분 detail.error에 고정된 코드가 담겨 있어요:
{"detail": {"error": "rate_limited", "retry_after": <seconds>, "message": "…"}}| 상태 | detail.error | 의미 |
|---|---|---|
| 400 | invalid_image_urlimage_url_unreachableimage_url_too_largeimage_url_not_image | 보낸 그대로는 요청을 처리할 수 없어요. 다운로드할 수 없는 이미지 링크, 잘못된 매개변수나 콜백 URL 등이 원인이에요. 비용은 청구되지 않아요. |
| 401 | invalid_api_key | 키가 없거나, 잘못됐거나, 폐기됐어요. |
| 402 | insufficient_balancemonthly_limit_reachedkey_limit_reached | API 잔액이 부족하거나 월간 한도(계정 또는 키)에 도달했어요. |
| 403 | subscription_requiredsession_required | 웹사이트에서 만든 모델을 다운로드하려면 웹사이트 로그인 세션이나 요금제가 필요해요. |
| 404 | feature_off | 찾을 수 없거나 아직 사용할 수 없어요. |
| 409 | file_not_ready | 모델 파일이 아직 준비되지 않았어요. |
| 409 | idempotency_key_reusedidempotency_in_progress | 이 Idempotency-Key가 이미 다른 요청에 사용됐거나, 첫 요청이 아직 실행 중이에요. |
| 429 | rate_limitedtoo_many_jobs | 요청 한도에 도달했거나 동시에 실행 중인 생성이 너무 많아요. |
요금
실시간 API 요금표 기준 모델 1개당 비용(미국 달러)이에요.
| 버전 | 사진 1장 | 2–4개 각도 |
|---|---|---|
Wandy 1/generate/cloud/fast | US$0.09 | US$0.24 |
Wandy 1.1/generate/cloud | US$0.15 | US$0.27 |
Wandy 2/generate/cloud/ultra | US$0.18 | US$0.30 |
유료 호출은 모두 선불 API 잔액에서 미국 달러로 청구돼요. 카드로 $5부터 충전할 수 있고, 잔액은 만료되지 않으며 실패한 작업은 자동으로 환불돼요.
API로 생성한 모델은 모든 형식으로 무료로 다운로드할 수 있어요.
Google 또는 Apple로 로그인한 신규 계정은 첫 API 키에 US$2.00를 받아요. 1회 한정이며 카드는 필요 없어요.
엔드포인트
공개 API를 한 표에 담았어요. 모든 경로에 같은 Bearer 키를 사용해요.
생성
| 메서드 | 경로 | 기능 |
|---|---|---|
| POST | /generate/cloud/ultra | 사진 한 장으로 모델 만들기, Wandy 2유료 |
| POST | /generate/cloud | 사진 1장으로 모델 만들기, Wandy 1.1유료 |
| POST | /generate/cloud/fast | 사진 1장으로 모델 만들기, Wandy 1유료 |
| POST | /generate/cloud/multi/ultra | 2–4개 각도로 모델 만들기, Wandy 2유료 |
| POST | /generate/cloud/multi | 한 대상의 2–4개 각도로 모델 만들기, Wandy 1.1유료 |
| POST | /generate/cloud/multi/fast | 2–4개 각도로 모델 만들기, Wandy 1유료 |
| POST | /generate/text/imagine | 텍스트 프롬프트 → 콘셉트 이미지유료 |
| POST | /generate/text | 콘셉트 이미지 → 3D 모델유료 |
| POST | /generate/retexture | 사진으로 모델에 새 텍스처 입히기유료 |
작업
| 메서드 | 경로 | 기능 |
|---|---|---|
| GET | /task/{task_id}/status | 생성 진행 상황 |
| GET | /api/generate/eta | 현재 생성에 걸리는 시간 |
라이브러리
| 메서드 | 경로 | 기능 |
|---|---|---|
| GET | /library | 내 모델, 최신순 |
| GET | /model/{model_id} | 모델 하나의 GLB 링크와 정보 |
| DELETE | /model/{model_id} | 모델 삭제 |
| GET | /model/{model_id}/versions | 모델의 모든 버전과 각 버전으로 만든 파일 |
다운로드 및 후처리
| 메서드 | 경로 | 기능 |
|---|---|---|
| GET | /model/{model_id}/stream | 모델의 GLB 파일다운로드 |
| GET | /model/{model_id}/export | GLB, FBX, OBJ, USDZ, STL 또는 Draco GLB로 다운로드다운로드 |
| GET | /model/{model_id}/print | 출력 검사 리포트가 포함된 출력용 STL 또는 3MF다운로드 |
| GET | /model/{model_id}/retopo | 텍스처를 베이크한 쿼드 리메시 또는 Low Poly유료다운로드 |
| GET | /model/{model_id}/rig | 애니메이션 클립이 포함된 자동 리깅유료 |
| GET | /model/{model_id}/parts | 모델을 파트별로 나누기유료 |
| GET | /model/{model_id}/gamepack | LOD와 콜라이더가 포함된 게임용 패키지유료다운로드 |
| GET | /model/{model_id}/make/{kind} | 페이퍼크래프트 같은 공작물 만들기유료 |
| GET | /model/{model_id}/outputs/{output_id} | 이전에 만든 파일 다시 열기 |
| GET | /model/{model_id}/rig/suggest | 어떤 리그가 맞는지 확인(결제 전, 무료) |
계정
| 메서드 | 경로 | 기능 |
|---|---|---|
| GET | /api/platform/balance | API 잔액 |
| GET | /api/platform/prices | 실시간 가격표 |
각 작업의 모든 응답과 오류는 OpenAPI 문서에 타입과 예시로 정리되어 있어요. 이 문서로 클라이언트를 생성하거나 코딩 에이전트에게 맡겨 보세요.
링크와 재시도
파일을 업로드하는 대신 링크를 보내고, 요청을 반복해도 두 번 결제되지 않아요.
링크로 사진 보내기
모든 사진 경로는 image_url이 담긴 JSON도 받아요. 여러 각도는 image_urls를 사용하세요. 이미지를 내려받아 업로드한 파일과 똑같이 처리해요. 링크는 공개 주소의 https여야 하고, 파일은 20 MB 이하의 JPEG, PNG 또는 WebP여야 해요. 사용할 수 없는 링크는 비용이 차감되기 전에 400으로 응답해요.
# One photo by link (Wandy 2) — no uploadcurl -s -X POST "https://api.wandy3d.com/generate/cloud/ultra" \ -H "Authorization: Bearer $WANDY3D_API_KEY" \ -H "Content-Type: application/json" \ -d '{"image_url": "https://images.example.org/chair.jpg"}'# → {"task_id": "<task_id>", "status": "queued", "billing": {…}}# Several views of one object: image_urls, front view firstcurl -s -X POST "https://api.wandy3d.com/generate/cloud/multi/ultra" \ -H "Authorization: Bearer $WANDY3D_API_KEY" \ -H "Content-Type: application/json" \ -d '{"image_urls": ["https://images.example.org/front.jpg", "https://images.example.org/side.jpg"]}'# A link we can't use → 400, nothing is charged# {"detail": {"error": "invalid_image_url", "message": "image_url must use https://."}}안전한 재시도
유료 POST 요청에 Idempotency-Key 헤더를 추가하세요. 시간 초과나 큐의 재시도로 같은 요청이 24시간 안에 다시 들어오면 같은 task_id가 담긴 첫 응답을 받게 되고, 작업이 다시 시작되거나 비용이 또 차감되지 않아요. 같은 키로 다른 요청을 보내면 409로 응답해요.
KEY=$(uuidgen) # one key per job you want to exist oncecurl -si -X POST "https://api.wandy3d.com/generate/cloud/ultra" \ -H "Authorization: Bearer $WANDY3D_API_KEY" \ -H "Idempotency-Key: $KEY" \ -H "Content-Type: application/json" \ -d '{"image_url": "https://images.example.org/chair.jpg"}'# → 200 {"task_id": "<task_id>", "status": "queued", "billing": {"cost_usd": "<price>", …}}# The connection dropped? Send exactly the same request again (within 24 hours):# → 200, header Idempotent-Replayed: true, the same "task_id" — no second job, no second charge# The same key with a different request → 409# {"detail": {"error": "idempotency_key_reused", "message": "…"}}웹훅
폴링은 그만: 생성을 시작할 때 callback_url을 추가하면, 생성이 끝났을 때 서명된 이벤트 하나를 서버로 POST해 드려요.
curl -s -X POST "https://api.wandy3d.com/generate/cloud/ultra?callback_url=https://your.app/hooks/wandy3d" \ -H "Authorization: Bearer $WANDY3D_API_KEY" -F "file=@photo.jpg"# → {"task_id": "…", "webhook": {"callback_url": "https://your.app/hooks/wandy3d", …}}# When the model is ready (or the job fails) we POST one signed event to that URL.이벤트
task.completed — 모델이 준비됐어요. id, 이름, 모델 링크와 GLB 내보내기 링크가 포함돼요. task.failed — 작업이 실패했고 비용은 API 잔액으로 돌아갔어요. ping — 대시보드에서 보내는 테스트예요.
서명 포함
모든 이벤트에는 Wandy-Signature: t=…,v1=…가 포함돼요. v1은 타임스탬프, 점, 원본 본문을 이어 붙인 값의 HMAC-SHA256이며, 작업을 시작한 API 키의 웹훅 시크릿을 키로 사용해요. 5분이 지난 이벤트는 거부하세요.
자동 재시도
10초 안에 2xx로 응답하세요. 그 외의 경우 30초, 2분, 10분 후에 같은 이벤트 id로 3번 재시도하니 중복은 쉽게 걸러낼 수 있어요.
POST /hooks/wandy3dWandy-Signature: t=1761900000,v1=5f0c…Wandy-Event-Id: evt_…Wandy-Event-Type: task.completed{ "id": "evt_…", "type": "task.completed", "created_at": "…", "data": { "task_id": "…", "status": "done", "model_id": "…", "name": "…", "model_url": "https://api.wandy3d.com/model/<model_id>", "export_url": "https://api.wandy3d.com/model/<model_id>/export?format=glb", "cost_usd": "…" }}import crypto from "node:crypto";import express from "express";const app = express();// The signature covers the raw body: read it as bytes, parse after the check.app.post("/hooks/wandy3d", express.raw({ type: "application/json" }), (req, res) => { const parts = Object.fromEntries( (req.get("Wandy-Signature") ?? "").split(",").map((p) => p.split("=")), ); const expected = crypto .createHmac("sha256", process.env.WANDY3D_WEBHOOK_SECRET) .update(`${parts.t}.`) .update(req.body) .digest("hex"); const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300; const valid = typeof parts.v1 === "string" && parts.v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected)); if (!fresh || !valid) return res.sendStatus(400); const event = JSON.parse(req.body.toString("utf8")); if (event.type === "task.completed") { console.log("model ready:", event.data.model_id, event.data.export_url); } res.sendStatus(200); // answer fast; do slow work after});app.listen(3000);AI 에이전트와 함께 사용하기
Claude, ChatGPT, Cursor, VS Code 등 MCP를 지원하는 앱에 Wandy3D를 연결하세요. 평소 말하듯 3D 모델을 요청하면 어시스턴트가 내 Wandy3D 계정에서 모델을 만들어 채팅에 바로 보여 줘요.
서버 URL
https://wandy3d.com/mcp클릭 한 번으로 에디터에 추가
에디터가 열리면 서버를 추가하기 전에 확인을 요청해요. 예시 모델 둘러보기와 가격 확인은 바로 사용할 수 있어요. 모델을 생성하려면 먼저 API 키를 붙여 넣으세요. 버튼이 키를 에디터 설정으로 전달해요.
키는 브라우저에만 남아요. 에디터를 여는 링크에만 들어가요.
두 가지 연결 방법
Wandy3D로 로그인
커넥터를 지원하는 Claude, ChatGPT 등 채팅 앱
- 앱의 커넥터 설정에서 위의 서버 URL로 맞춤 커넥터를 추가하세요.
- 앱에서 요청하면 Wandy3D로 로그인한 뒤 연결을 허용하세요.
- 모델을 요청하세요. 웹사이트와 같은 가격으로 Wandy3D 크레딧을 사용해 만들어져요.
API 키 사용
Claude Code, Cursor, VS Code와 직접 만든 스크립트
- API 플랫폼에서 키를 만들고 API 잔액을 충전하세요.
Authorization헤더에 키를 넣어 서버를 추가하세요. 예시는 아래에 있어요.- 호출 비용은 API 잔액에서 미국 달러로 결제되고, 이렇게 만든 모델은 무료로 다운로드할 수 있어요.
claude mcp add --transport http wandy3d \ https://wandy3d.com/mcp \ --header "Authorization: Bearer hg_live_…"hg_live_…를 API 플랫폼에서 받은 키로 바꾸세요. Cursor는 ~/.cursor/mcp.json, VS Code는 .vscode/mcp.json을 읽어요. Authorization 헤더를 보낼 수 있는 MCP 클라이언트라면 모두 사용할 수 있어요.
어시스턴트가 할 수 있는 일
generate_from_image사진, 렌더 또는 그림으로 3D 모델 만들기generate_from_text설명으로 3D 모델 만들기get_task생성 과정을 확인하고 완성된 모델 보여 주기list_models내 라이브러리 둘러보기get_model내 모델 하나 열기export_modelGLB, FBX, OBJ, USDZ 또는 STL 다운로드check_print3D 프린팅 가능 여부 무료 점검: 판정, 출력 크기, 재료, 출력 시간, 수리make_low_poly게임, AR, 웹용 Low Poly 버전 만들기rig_model모델에 스켈레톤과 기본 애니메이션 리깅하기list_animations리깅된 모델의 애니메이션 클립 목록 보기animate_face모델 얼굴 애니메이션: 표정 셰이프와 기본 클립(미소, 눈 깜빡임, 말하기 등)make_craft모델을 페이퍼크래프트, 레이저 커팅 레이어, 브릭 세트 또는 플렉시 토이로 바꾸기get_credits잔액과 가격 확인: 크레딧, 또는 키로 연결한 경우 API 잔액browse_gallery3D 뷰어로 예시 모델 보기, 로그인 없이get_prices현재 가격을 크레딧으로 확인하기, 로그인 없이
채팅 속 3D 뷰어
MCP Apps를 지원하는 클라이언트에서는 완성된 모델이 대화 안의 인터랙티브 뷰어로 열려요. 돌려 보고, 클레이 모드로 바꾸고, Wandy3D에서 열 수 있어요. 다른 클라이언트에서는 미리보기 이미지와 링크가 표시돼요.
가격을 먼저 확인해요
Wandy3D가 유료 작업마다 비용을 어시스턴트에게 알려 주기 때문에, 어시스턴트가 사용 전에 먼저 확인을 받을 수 있어요. 실패한 생성은 환불돼요. 크레딧으로 만든 모델의 파일은 요금제, 1회 잠금 해제 또는 크레딧으로 다운로드할 수 있어요. 가격을 먼저 알려 주니 어시스턴트가 미리 확인을 받을 수 있어요.
첫 API 호출을 해 보세요
API 플랫폼에서 키를 만들고 잔액을 충전하세요. 1분이면 끝나요.
지오메트리 보정 — Powered by Hi3D 1.0

