Wandy3D API
Tạo mô hình 3D từ mã, engine hoặc AI agent của bạn
Gửi một ảnh, vài góc nhìn hoặc một câu mô tả và nhận về mô hình 3D có texture — rồi xuất, in 3D, remesh thành lưới tứ giác, gắn xương hoặc đóng gói cho game engine. Cùng quy trình như trong studio, qua HTTPS thông thường.
Từ 0,09 US$ mỗi mô hình (Wandy 1) · Wandy 2 0,18 US$
2,00 US$ dùng thử miễn phí — khoảng 11 mô hình Wandy 2 hoặc 22 mô hình Wandy 1 với khóa API đầu tiên của bạn.
- Số dư trả trước không bao giờ hết hạn · không cần đăng ký gói
- Xác thực bằng khóa Bearer
- 60 yêu cầu mỗi phút cho mỗi khóa
- REST và JSON qua HTTPS
# 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>"}, …}Bắt đầu nhanh
Bốn bước từ ảnh đến tệp GLB.
- 1
Tạo khóa
Trong nền tảng API, mục Khóa API, rồi nạp tiền vào số dư API. Khóa chỉ hiện một lần — hãy lưu nó trong biến môi trường, ví dụ
WANDY3D_API_KEY. - 2
Bắt đầu tạo mô hình
POST
/generate/cloud/ultraGửi một ảnh qua trường multipart
file. Phản hồi sẽ cótask_id. - 3
Kiểm tra tác vụ
GET
/task/{task_id}/statusCứ vài giây một lần, cho đến khi
statuslàdone; lúc đó phản hồi sẽ cómodel_id. - 4
Tải xuống
GET
/model/{model_id}/export?format=glbGLB phản hồi ngay với liên kết ngắn hạn. Các định dạng khác cần chuyển đổi trước — hãy kiểm tra lại cùng URL cho đến khi sẵn sàng.
# 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>"Khóa và giới hạn
Mỗi yêu cầu đều gửi khóa của bạn trong header Authorization.
Authorization: Bearer hg_live_…Giữ bí mật khóa
Khóa hoạt động thay bạn và chi tiêu số dư API của bạn. Hãy dùng nó từ máy chủ, script hoặc CI — không bao giờ dùng trong trang web hay ứng dụng di động. Nếu khóa bị lộ, hãy thu hồi trong nền tảng API: khóa sẽ ngừng hoạt động ngay.
Giới hạn tần suất
60 yêu cầu mỗi phút cho mỗi khóa. Vượt giới hạn, phản hồi là 429 kèm retry_after — số giây cần chờ.
Tối đa 10 khóa
Dùng một khóa cho mỗi ứng dụng hoặc máy, để có thể thu hồi một khóa mà không ảnh hưởng các khóa khác.
Lỗi
Lỗi được trả về dạng JSON. Hầu hết có mã cố định trong detail.error:
{"detail": {"error": "rate_limited", "retry_after": <seconds>, "message": "…"}}| Trạng thái | detail.error | Ý nghĩa |
|---|---|---|
| 400 | invalid_image_urlimage_url_unreachableimage_url_too_largeimage_url_not_image | Yêu cầu không dùng được như đã gửi: liên kết ảnh không tải được, tham số hoặc URL callback không hợp lệ. Không bị trừ phí. |
| 401 | invalid_api_key | Khóa bị thiếu, sai hoặc đã bị thu hồi. |
| 402 | insufficient_balancemonthly_limit_reachedkey_limit_reached | Không đủ số dư API, hoặc đã đạt giới hạn hằng tháng (của tài khoản hoặc khóa). |
| 403 | subscription_requiredsession_required | Cần phiên đăng nhập trên website, hoặc cần gói để tải mô hình được tạo trên website. |
| 404 | feature_off | Không tìm thấy, hoặc bạn chưa thể truy cập. |
| 409 | file_not_ready | Tệp mô hình chưa sẵn sàng. |
| 409 | idempotency_key_reusedidempotency_in_progress | Idempotency-Key đã được dùng với một yêu cầu khác, hoặc yêu cầu đầu tiên dùng nó vẫn đang chạy. |
| 429 | rate_limitedtoo_many_jobs | Đã đạt giới hạn tần suất, hoặc có quá nhiều lượt tạo đang chạy cùng lúc. |
Bảng giá
Giá của một mô hình, tính bằng đô la Mỹ, theo bảng giá API hiện hành.
| Phiên bản | Một ảnh | 2–4 góc nhìn |
|---|---|---|
Wandy 1/generate/cloud/fast | 0,09 US$ | 0,24 US$ |
Wandy 1.1/generate/cloud | 0,15 US$ | 0,27 US$ |
Wandy 2/generate/cloud/ultra | 0,18 US$ | 0,30 US$ |
Mỗi lệnh gọi trả phí được tính bằng đô la Mỹ từ số dư API trả trước của bạn. Nạp bằng thẻ từ $5 — số dư không bao giờ hết hạn, và tác vụ thất bại được hoàn tiền tự động.
Mô hình bạn tạo qua API thuộc về bạn, tải xuống miễn phí ở mọi định dạng.
Tài khoản mới đăng nhập bằng Google hoặc Apple nhận 2,00 US$ cho khóa API đầu tiên — một lần, không cần thẻ.
Endpoint
Toàn bộ API công khai trong một bảng. Mọi route đều dùng cùng một khóa Bearer.
Tạo
| Phương thức | Đường dẫn | Chức năng |
|---|---|---|
| POST | /generate/cloud/ultra | Mô hình từ một ảnh, Wandy 2Trả phí |
| POST | /generate/cloud | Mô hình từ một ảnh, Wandy 1.1Trả phí |
| POST | /generate/cloud/fast | Mô hình từ một ảnh, Wandy 1Trả phí |
| POST | /generate/cloud/multi/ultra | Mô hình từ 2–4 góc chụp, Wandy 2Trả phí |
| POST | /generate/cloud/multi | Mô hình từ 2–4 góc nhìn của một vật thể, Wandy 1.1Trả phí |
| POST | /generate/cloud/multi/fast | Mô hình từ 2–4 góc chụp, Wandy 1Trả phí |
| POST | /generate/text/imagine | Prompt văn bản → ảnh ý tưởngTrả phí |
| POST | /generate/text | Ảnh ý tưởng → mô hình 3DTrả phí |
| POST | /generate/retexture | Texture mới cho mô hình từ một ảnhTrả phí |
Tác vụ
| Phương thức | Đường dẫn | Chức năng |
|---|---|---|
| GET | /task/{task_id}/status | Tiến độ tạo mô hình |
| GET | /api/generate/eta | Thời gian tạo mô hình hiện tại |
Thư viện
| Phương thức | Đường dẫn | Chức năng |
|---|---|---|
| GET | /library | Mô hình của bạn, mới nhất trước |
| GET | /model/{model_id} | Một mô hình, liên kết GLB và thông tin về vật thể |
| DELETE | /model/{model_id} | Xóa mô hình |
| GET | /model/{model_id}/versions | Mọi phiên bản của mô hình và các tệp tạo từ đó |
Tải xuống và hậu xử lý
| Phương thức | Đường dẫn | Chức năng |
|---|---|---|
| GET | /model/{model_id}/stream | Tệp GLB của mô hìnhTải xuống |
| GET | /model/{model_id}/export | Tải xuống dạng GLB, FBX, OBJ, USDZ, STL hoặc Draco GLBTải xuống |
| GET | /model/{model_id}/print | STL hoặc 3MF sẵn sàng để in, kèm báo cáo kiểm tra inTải xuống |
| GET | /model/{model_id}/retopo | Remesh tứ giác hoặc Low Poly kèm texture đã bakeTrả phíTải xuống |
| GET | /model/{model_id}/rig | Tự động gắn xương kèm clip hoạt ảnhTrả phí |
| GET | /model/{model_id}/parts | Tách mô hình thành các phầnTrả phí |
| GET | /model/{model_id}/gamepack | Gói sẵn sàng cho game, kèm LOD và colliderTrả phíTải xuống |
| GET | /model/{model_id}/make/{kind} | Đồ thủ công, ví dụ mô hình giấyTrả phí |
| GET | /model/{model_id}/outputs/{output_id} | Mở lại tệp đã tạo trước đó |
| GET | /model/{model_id}/rig/suggest | Bộ xương nào phù hợp — miễn phí, trước khi thanh toán |
Tài khoản
| Phương thức | Đường dẫn | Chức năng |
|---|---|---|
| GET | /api/platform/balance | Số dư API của bạn |
| GET | /api/platform/prices | Bảng giá hiện hành |
Mọi phản hồi và mọi lỗi của từng thao tác đều được định kiểu trong tài liệu OpenAPI, kèm ví dụ. Hãy tạo client từ tài liệu này hoặc giao nó cho trợ lý lập trình AI của bạn.
Liên kết và gửi lại
Gửi liên kết thay vì tải tệp lên, và lặp lại yêu cầu mà không phải trả tiền hai lần.
Ảnh qua liên kết
Mọi route nhận ảnh đều chấp nhận JSON với image_url; với nhiều góc chụp, dùng image_urls. Chúng tôi tải ảnh về và xử lý y như tệp tải lên. Liên kết phải là https trên địa chỉ công khai, và tệp phải là JPEG, PNG hoặc WebP tối đa 20 MB. Liên kết không dùng được sẽ trả về 400 trước khi bị tính phí.
# 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://."}}Gửi lại an toàn
Thêm header Idempotency-Key vào POST trả phí. Nếu cùng yêu cầu đó đến lại trong vòng 24 giờ — do hết thời gian chờ hay hàng đợi của bạn gửi lại — bạn sẽ nhận phản hồi đầu tiên với cùng task_id, và không có gì được khởi chạy hay tính phí lần thứ hai. Cùng khóa nhưng khác yêu cầu sẽ trả về 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": "…"}}Webhook
Không cần hỏi trạng thái liên tục: thêm callback_url khi bắt đầu tạo mô hình, và chúng tôi sẽ POST một sự kiện có chữ ký đến máy chủ của bạn khi hoàn tất.
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.Sự kiện
task.completed — mô hình đã sẵn sàng, kèm id, tên và liên kết đến mô hình cùng bản xuất GLB. task.failed — tác vụ thất bại và khoản phí đã được hoàn vào số dư API. ping — sự kiện thử bạn gửi từ bảng điều khiển.
Có chữ ký
Mỗi sự kiện đều có Wandy-Signature: t=…,v1=… — v1 là HMAC-SHA256 của dấu thời gian, một dấu chấm và phần thân thô, dùng khóa bí mật webhook của khóa API đã khởi chạy tác vụ. Hãy từ chối các sự kiện cũ hơn 5 phút.
Có gửi lại
Hãy phản hồi bằng bất kỳ mã 2xx nào trong vòng 10 giây. Nếu không, sự kiện sẽ được gửi lại 3 lần — sau 30 s, 2 phút và 10 phút — với cùng id sự kiện, nên dễ dàng bỏ qua bản trùng.
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);Dùng với trợ lý AI
Kết nối Wandy3D với Claude, ChatGPT, Cursor, VS Code hoặc bất kỳ ứng dụng nào hỗ trợ MCP. Chỉ cần yêu cầu mô hình 3D bằng lời thường: trợ lý sẽ tạo trong tài khoản Wandy3D của bạn và hiển thị ngay trong cuộc trò chuyện.
URL máy chủ
https://wandy3d.com/mcpThêm vào trình soạn thảo chỉ với một cú nhấp
Trình soạn thảo sẽ mở ra và hỏi bạn trước khi thêm máy chủ. Xem mô hình mẫu và bảng giá dùng được ngay. Để tạo mô hình, hãy dán khóa API trước: các nút sẽ đưa khóa vào phần cài đặt của trình soạn thảo.
Khóa chỉ nằm trong trình duyệt của bạn: nó chỉ được đưa vào liên kết mở trình soạn thảo.
Hai cách kết nối
Đăng nhập bằng Wandy3D
Claude, ChatGPT và các ứng dụng chat khác có connector
- Trong phần cài đặt connector của ứng dụng, thêm một connector tùy chỉnh với URL máy chủ ở trên.
- Đăng nhập bằng Wandy3D khi ứng dụng yêu cầu, rồi cho phép kết nối.
- Yêu cầu một mô hình. Mô hình được tạo bằng tín dụng Wandy3D của bạn theo giá trên trang web.
Dùng khóa API
Claude Code, Cursor, VS Code và script của riêng bạn
- Tạo khóa trên nền tảng API và nạp tiền vào số dư API.
- Thêm máy chủ với khóa trong header
Authorization— xem đoạn mã bên dưới. - Lệnh gọi được trả bằng đô la Mỹ từ số dư API, và mô hình tạo theo cách này được tải xuống miễn phí.
claude mcp add --transport http wandy3d \ https://wandy3d.com/mcp \ --header "Authorization: Bearer hg_live_…"Thay hg_live_… bằng khóa từ nền tảng API. Cursor đọc ~/.cursor/mcp.json, VS Code đọc .vscode/mcp.json; mọi client MCP gửi được header Authorization đều dùng được.
Trợ lý có thể làm gì
generate_from_imageTạo mô hình 3D từ ảnh chụp, ảnh render hoặc bản vẽgenerate_from_textTạo mô hình 3D từ một đoạn mô tảget_taskTheo dõi quá trình tạo và hiển thị mô hình hoàn chỉnhlist_modelsDuyệt thư viện của bạnget_modelMở một mô hình của bạnexport_modelTải xuống GLB, FBX, OBJ, USDZ hoặc STLcheck_printKiểm tra mô hình để in 3D, miễn phí: kết luận, kích thước in, vật liệu, thời gian in, sửa lỗimake_low_polyTạo phiên bản Low Poly cho game, AR và webrig_modelGắn xương và hoạt ảnh có sẵn cho mô hìnhlist_animationsLiệt kê clip hoạt ảnh của mô hình đã gắn xươnganimate_faceTạo biểu cảm cho khuôn mặt mô hình: các hình biểu cảm và clip có sẵn — cười, chớp mắt, nói chuyện và hơn thếmake_craftBiến mô hình thành mô hình giấy, lớp cắt laser, bộ gạch lắp ráp hoặc đồ chơi khớp độngget_creditsXem số dư và giá: tín dụng, hoặc số dư API khi bạn kết nối bằng khóabrowse_galleryXem mô hình mẫu trong trình xem 3D, không cần đăng nhậpget_pricesXem giá hiện tại bằng tín dụng, không cần đăng nhập
Trình xem 3D ngay trong cuộc trò chuyện
Với các client hỗ trợ MCP Apps, mô hình hoàn chỉnh mở trong trình xem tương tác ngay trong cuộc trò chuyện: xoay quanh, chuyển sang chế độ đất sét, mở trong Wandy3D. Các client khác nhận ảnh xem trước và một liên kết.
Bạn thấy giá trước
Wandy3D báo cho trợ lý chi phí của từng thao tác trả phí, để nó hỏi lại bạn trước khi chi tiêu. Lượt tạo thất bại sẽ được hoàn lại. Tệp của mô hình tạo bằng tín dụng được tải xuống khi có gói thuê bao, sau khi mở khóa một lần hoặc bằng tín dụng: giá luôn được báo trước để trợ lý hỏi lại bạn.
Thực hiện lệnh gọi API đầu tiên
Tạo khóa và nạp tiền trên nền tảng API — chỉ mất một phút.
Tinh chỉnh hình học — Powered by Hi3D 1.0

