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. 1

    키 만들기

    API 플랫폼의 API 키에서 키를 만든 다음 API 잔액을 충전하세요. 키는 한 번만 표시되니 WANDY3D_API_KEY 같은 환경 변수에 보관하세요.

  2. 2

    생성 시작

    POST/generate/cloud/ultra

    사진 한 장을 multipart 필드 file로 보내세요. 응답에 task_id가 담겨 와요.

  3. 3

    작업 상태 확인

    GET/task/{task_id}/status

    status가 done이 될 때까지 몇 초마다 확인하세요. 완료되면 응답에 model_id가 담겨 와요.

  4. 4

    다운로드

    GET/model/{model_id}/export?format=glb

    GLB는 짧은 시간만 유효한 링크로 바로 응답해요. 다른 형식은 먼저 변환되니, 준비될 때까지 같은 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의미
400invalid_image_urlimage_url_unreachableimage_url_too_largeimage_url_not_image보낸 그대로는 요청을 처리할 수 없어요. 다운로드할 수 없는 이미지 링크, 잘못된 매개변수나 콜백 URL 등이 원인이에요. 비용은 청구되지 않아요.
401invalid_api_key키가 없거나, 잘못됐거나, 폐기됐어요.
402insufficient_balancemonthly_limit_reachedkey_limit_reachedAPI 잔액이 부족하거나 월간 한도(계정 또는 키)에 도달했어요.
403subscription_requiredsession_required웹사이트에서 만든 모델을 다운로드하려면 웹사이트 로그인 세션이나 요금제가 필요해요.
404feature_off찾을 수 없거나 아직 사용할 수 없어요.
409file_not_ready모델 파일이 아직 준비되지 않았어요.
409idempotency_key_reusedidempotency_in_progress이 Idempotency-Key가 이미 다른 요청에 사용됐거나, 첫 요청이 아직 실행 중이에요.
429rate_limitedtoo_many_jobs요청 한도에 도달했거나 동시에 실행 중인 생성이 너무 많아요.

요금

실시간 API 요금표 기준 모델 1개당 비용(미국 달러)이에요.

생성 모델 1개당 API 요금(미국 달러)
버전사진 1장2–4개 각도
Wandy 1/generate/cloud/fastUS$0.09US$0.24
Wandy 1.1/generate/cloudUS$0.15US$0.27
Wandy 2/generate/cloud/ultraUS$0.18US$0.30

유료 호출은 모두 선불 API 잔액에서 미국 달러로 청구돼요. 카드로 $5부터 충전할 수 있고, 잔액은 만료되지 않으며 실패한 작업은 자동으로 환불돼요.

API로 생성한 모델은 모든 형식으로 무료로 다운로드할 수 있어요.

Google 또는 Apple로 로그인한 신규 계정은 첫 API 키에 US$2.00를 받아요. 1회 한정이며 카드는 필요 없어요.

API 요금 보기

엔드포인트

공개 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 등 채팅 앱

  1. 앱의 커넥터 설정에서 위의 서버 URL로 맞춤 커넥터를 추가하세요.
  2. 앱에서 요청하면 Wandy3D로 로그인한 뒤 연결을 허용하세요.
  3. 모델을 요청하세요. 웹사이트와 같은 가격으로 Wandy3D 크레딧을 사용해 만들어져요.

API 키 사용

Claude Code, Cursor, VS Code와 직접 만든 스크립트

  1. API 플랫폼에서 키를 만들고 API 잔액을 충전하세요.
  2. Authorization 헤더에 키를 넣어 서버를 추가하세요. 예시는 아래에 있어요.
  3. 호출 비용은 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분이면 끝나요.

API 키 받기

지오메트리 보정 — Powered by Hi3D 1.0