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

    Bắt đầu tạo mô hình

    POST/generate/cloud/ultra

    Gửi một ảnh qua trường multipart file. Phản hồi sẽ có task_id.

  3. 3

    Kiểm tra tác vụ

    GET/task/{task_id}/status

    Cứ vài giây một lần, cho đến khi status là done; lúc đó phản hồi sẽ có model_id.

  4. 4

    Tải xuống

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

    GLB 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áidetail.errorÝ nghĩa
400invalid_image_urlimage_url_unreachableimage_url_too_largeimage_url_not_imageYê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í.
401invalid_api_keyKhóa bị thiếu, sai hoặc đã bị thu hồi.
402insufficient_balancemonthly_limit_reachedkey_limit_reachedKhô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).
403subscription_requiredsession_requiredCầ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.
404feature_offKhông tìm thấy, hoặc bạn chưa thể truy cập.
409file_not_readyTệp mô hình chưa sẵn sàng.
409idempotency_key_reusedidempotency_in_progressIdempotency-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.
429rate_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.

Giá API cho mỗi mô hình được tạo, tính bằng đô la Mỹ
Phiên bảnMột ảnh2–4 góc nhìn
Wandy 1/generate/cloud/fast0,09 US$0,24 US$
Wandy 1.1/generate/cloud0,15 US$0,27 US$
Wandy 2/generate/cloud/ultra0,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ẻ.

Xem giá API

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ẫnChứ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ẫnChứ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ẫnChứ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ẫnChứ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ẫnChứ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.

Khóa bí mật webhook và sự kiện thử
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/mcp

Thê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

  1. 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.
  2. Đăng nhập bằng Wandy3D khi ứng dụng yêu cầu, rồi cho phép kết nối.
  3. 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

  1. Tạo khóa trên nền tảng API và nạp tiền vào số dư API.
  2. Thêm máy chủ với khóa trong header Authorization — xem đoạn mã bên dưới.
  3. 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ỉnh
  • list_modelsDuyệt thư viện của bạn
  • get_modelMở một mô hình của bạn
  • export_modelTải xuống GLB, FBX, OBJ, USDZ hoặc STL
  • check_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ỗi
  • make_low_polyTạo phiên bản Low Poly cho game, AR và web
  • rig_modelGắn xương và hoạt ảnh có sẵn cho mô hình
  • list_animationsLiệt kê clip hoạt ảnh của mô hình đã gắn xương
  • animate_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 động
  • get_creditsXem số dư và giá: tín dụng, hoặc số dư API khi bạn kết nối bằng khóa
  • browse_galleryXem mô hình mẫu trong trình xem 3D, không cần đăng nhập
  • get_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.

Lấy khóa API

Tinh chỉnh hình học — Powered by Hi3D 1.0