Wandy3D API
Genera modelos 3D desde tu código, tu motor o tu agente de IA
Envía una foto, varias vistas o una frase y recibe un modelo 3D con textura; luego expórtalo, imprímelo, remállalo en quads, ponle un rig o prepáralo para tu motor de juego. El mismo proceso que en el estudio, por HTTPS sin complicaciones.
Desde 0,09 US$ por modelo (Wandy 1) · Wandy 2 0,18 US$
2,00 US$ gratis para probar — unos 11 modelos Wandy 2 o 22 modelos Wandy 1 con tu primera clave de API.
- Saldo prepago que nunca vence · sin suscripción
- Autenticación con clave Bearer
- 60 solicitudes por minuto por clave
- REST y JSON por 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>"}, …}Guía rápida
Cuatro pasos de una foto a un archivo GLB.
- 1
Crea una clave
En la plataforma de API, en «Claves de API»; después recarga tu saldo de API. La clave se muestra una sola vez: guárdala en una variable de entorno como
WANDY3D_API_KEY. - 2
Inicia una generación
POST
/generate/cloud/ultraEnvía una foto en el campo multipart
file. La respuesta incluye untask_id. - 3
Consulta la tarea
GET
/task/{task_id}/statusCada pocos segundos, hasta que
statusseadone; entonces la respuesta incluye elmodel_id. - 4
Descarga
GET
/model/{model_id}/export?format=glbGLB responde al instante con un enlace temporal. Los demás formatos se convierten primero: consulta la misma URL hasta que esté listo.
# 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>"Claves y límites
Cada solicitud lleva tu clave en el encabezado Authorization.
Authorization: Bearer hg_live_…Mantén tus claves en secreto
Una clave actúa en tu nombre y gasta tu saldo de API. Úsala desde tu servidor, scripts o CI — nunca en una página web ni en una app móvil. Si se filtra una clave, revócala en la plataforma de API: deja de funcionar al instante.
Límite de solicitudes
60 solicitudes por minuto por clave. Si superas el límite, la respuesta es 429 con retry_after: los segundos que debes esperar.
Hasta 10 claves
Usa una por app o máquina, así puedes revocar una sin tocar las demás.
Errores
Los errores vienen en JSON. La mayoría incluye un código estable en detail.error:
{"detail": {"error": "rate_limited", "retry_after": <seconds>, "message": "…"}}| Estado | detail.error | Significado |
|---|---|---|
| 400 | invalid_image_urlimage_url_unreachableimage_url_too_largeimage_url_not_image | La solicitud no se puede usar tal como se envió: un enlace de imagen que no podemos descargar, un parámetro o una URL de callback incorrectos. No se cobra nada. |
| 401 | invalid_api_key | Falta la clave, es incorrecta o fue revocada. |
| 402 | insufficient_balancemonthly_limit_reachedkey_limit_reached | No hay saldo de API suficiente o se alcanzó un límite mensual (de la cuenta o de la clave). |
| 403 | subscription_requiredsession_required | Requiere una sesión iniciada en el sitio web, o un plan para descargar un modelo creado en el sitio web. |
| 404 | feature_off | No encontrado, o aún no está disponible para ti. |
| 409 | file_not_ready | El archivo del modelo aún no está listo. |
| 409 | idempotency_key_reusedidempotency_in_progress | La Idempotency-Key ya se usó con otra solicitud, o su primera solicitud aún está en curso. |
| 429 | rate_limitedtoo_many_jobs | Se alcanzó el límite de solicitudes o hay demasiadas generaciones en curso a la vez. |
Precios
Lo que cuesta un modelo, en dólares estadounidenses, según la lista de precios vigente de la API.
| Versión | Una foto | 2–4 vistas |
|---|---|---|
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$ |
Cada llamada de pago se cobra en dólares estadounidenses desde tu saldo de API prepago. Recarga con tarjeta desde $5 — el saldo nunca vence y los trabajos fallidos se reembolsan automáticamente.
Los modelos que generas con la API son tuyos para descargar en todos los formatos, gratis.
Las cuentas nuevas que inician sesión con Google o Apple reciben 2,00 US$ en su primera clave de API — una sola vez, sin tarjeta.
Endpoints
La API pública en una tabla. Todas las rutas usan la misma clave Bearer.
Generar
| Método | Ruta | Qué hace |
|---|---|---|
| POST | /generate/cloud/ultra | Modelo a partir de una foto, Wandy 2De pago |
| POST | /generate/cloud | Modelo a partir de una foto, Wandy 1.1De pago |
| POST | /generate/cloud/fast | Modelo a partir de una foto, Wandy 1De pago |
| POST | /generate/cloud/multi/ultra | Modelo a partir de 2–4 vistas, Wandy 2De pago |
| POST | /generate/cloud/multi | Modelo a partir de 2–4 vistas de un objeto, Wandy 1.1De pago |
| POST | /generate/cloud/multi/fast | Modelo a partir de 2–4 vistas, Wandy 1De pago |
| POST | /generate/text/imagine | Prompt de texto → imagen conceptualDe pago |
| POST | /generate/text | Imagen conceptual → modelo 3DDe pago |
| POST | /generate/retexture | Nueva textura para un modelo a partir de una fotoDe pago |
Tareas
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /task/{task_id}/status | Progreso de una generación |
| GET | /api/generate/eta | Cuánto tarda una generación ahora mismo |
Biblioteca
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /library | Tus modelos, primero los más nuevos |
| GET | /model/{model_id} | Un modelo, su enlace GLB y qué es |
| DELETE | /model/{model_id} | Eliminar un modelo |
| GET | /model/{model_id}/versions | Todas las versiones de un modelo y los archivos creados a partir de ellas |
Descargas y posprocesado
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /model/{model_id}/stream | El archivo GLB del modeloDescarga |
| GET | /model/{model_id}/export | Descargar en GLB, FBX, OBJ, USDZ, STL o Draco GLBDescarga |
| GET | /model/{model_id}/print | STL o 3MF listo para imprimir con informe de revisiónDescarga |
| GET | /model/{model_id}/retopo | Remallado en quads o Low Poly con texturas horneadasDe pagoDescarga |
| GET | /model/{model_id}/rig | Rigging automático con animacionesDe pago |
| GET | /model/{model_id}/parts | Dividir un modelo en partesDe pago |
| GET | /model/{model_id}/gamepack | Pack para juegos con LOD y colisionadoresDe pagoDescarga |
| GET | /model/{model_id}/make/{kind} | Manualidades, por ejemplo papercraftDe pago |
| GET | /model/{model_id}/outputs/{output_id} | Volver a abrir un archivo creado antes |
| GET | /model/{model_id}/rig/suggest | Qué rig encaja — gratis, antes de pagar |
Cuenta
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /api/platform/balance | Tu saldo de la API |
| GET | /api/platform/prices | La lista de precios actual |
Todas las respuestas y todos los errores de cada operación están tipados en el documento OpenAPI, con ejemplos. Genera un cliente a partir de él o pásaselo a tu agente de programación.
Enlaces y reintentos
Envía un enlace en lugar de subir un archivo y repite una solicitud sin pagarla dos veces.
Una foto por enlace
Todas las rutas con foto también aceptan JSON con image_url; para varias vistas, image_urls. Descargamos la imagen y la tratamos exactamente igual que un archivo subido. El enlace debe ser https y apuntar a una dirección pública, y el archivo debe ser JPEG, PNG o WebP de hasta 20 MB. Si no podemos usar el enlace, respondemos 400 antes de cobrar nada.
# 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://."}}Reintentos seguros
Añade un encabezado Idempotency-Key a un POST de pago. Si la misma solicitud vuelve a llegar en menos de 24 horas — por un timeout o un reintento de tu cola —, recibes la primera respuesta con el mismo task_id, y no se inicia ni se cobra nada por segunda vez. La misma clave con una solicitud distinta responde 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": "…"}}Webhooks
Olvídate del polling: añade callback_url al iniciar una generación y, cuando termine, enviaremos un POST con un evento firmado a tu servidor.
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.Eventos
task.completed — el modelo está listo, con su id, nombre y enlaces al modelo y a su exportación GLB. task.failed — la tarea falló y su cargo vuelve a tu saldo de la API. ping — una prueba que envías desde el panel.
Firmados
Cada evento incluye Wandy-Signature: t=…,v1=… — v1 es el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo sin procesar, con el secreto de webhook de la clave de API que inició la tarea como clave. Rechaza los eventos con más de 5 minutos de antigüedad.
Con reintentos
Responde con cualquier 2xx en menos de 10 segundos. Cualquier otra respuesta se reintenta 3 veces — tras 30 s, 2 min y 10 min — con el mismo id de evento, así que es fácil descartar duplicados.
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);Úsalo con agentes de IA
Conecta Wandy3D a Claude, ChatGPT, Cursor, VS Code o cualquier app compatible con MCP. Pide un modelo 3D con tus propias palabras: el asistente lo crea en tu cuenta de Wandy3D y te lo muestra en el chat.
URL del servidor
https://wandy3d.com/mcpAñádelo a tu editor con un clic
El editor se abre y te pregunta antes de añadir el servidor. Explorar modelos de ejemplo y consultar precios funciona de inmediato. Para generar, primero pega tu clave de API: los botones la llevarán a la configuración del editor.
La clave se queda en tu navegador: solo va en el enlace que abre tu editor.
Dos formas de conectarte
Inicia sesión con Wandy3D
Claude, ChatGPT y otras apps de chat con conectores
- En la configuración de conectores de la app, añade un conector personalizado con la URL del servidor de arriba.
- Inicia sesión con Wandy3D cuando la app te lo pida y luego autoriza la conexión.
- Pide un modelo. Se crea con tus créditos de Wandy3D a los precios del sitio web.
Usa una clave de API
Claude Code, Cursor, VS Code y tus propios scripts
- Crea una clave en la plataforma de la API y recarga tu saldo de la API.
- Añade el servidor con la clave en el encabezado
Authorization— ejemplos abajo. - Las llamadas se pagan en dólares estadounidenses con tu saldo de la API, y los modelos creados así se descargan gratis.
claude mcp add --transport http wandy3d \ https://wandy3d.com/mcp \ --header "Authorization: Bearer hg_live_…"Reemplaza hg_live_… por una clave de la plataforma de la API. Cursor lee ~/.cursor/mcp.json y VS Code lee .vscode/mcp.json; funciona cualquier cliente MCP que pueda enviar un encabezado Authorization.
Qué puede hacer el asistente
generate_from_imageCrear un modelo 3D a partir de una foto, un render o un dibujogenerate_from_textCrear un modelo 3D a partir de una descripciónget_taskSeguir una generación y mostrar el modelo terminadolist_modelsExplorar tu bibliotecaget_modelAbrir uno de tus modelosexport_modelDescargar GLB, FBX, OBJ, USDZ o STLcheck_printRevisar un modelo para impresión 3D, gratis: veredicto, tamaño impreso, material, tiempo de impresión, reparacionesmake_low_polyCrear una versión Low Poly para juegos, AR y la webrig_modelAñadir a un modelo un esqueleto y animaciones listas para usarlist_animationsVer las animaciones de un modelo con riganimate_faceAnimar la cara de un modelo: formas de expresión y animaciones listas — sonreír, parpadear, hablar y másmake_craftConvertir un modelo en papercraft, capas para corte láser, un set de bloques o un juguete flexiget_creditsConsultar tu saldo y los precios: créditos, o tu saldo de la API si te conectas con una clavebrowse_galleryVer modelos de ejemplo en el visor 3D, sin iniciar sesiónget_pricesVer los precios actuales en créditos, sin iniciar sesión
Visor 3D en el chat
En los clientes compatibles con MCP Apps, los modelos terminados se abren en un visor interactivo dentro de la conversación: puedes girarlos, cambiar a vista de arcilla o abrirlos en Wandy3D. Los demás clientes reciben una imagen de vista previa y un enlace.
Ves el precio antes
Wandy3D le indica al asistente cuánto cuesta cada acción de pago, para que pueda consultarte antes de gastar. Si una generación falla, se reembolsa. Los archivos de los modelos creados con créditos se descargan con un plan, con un desbloqueo único o por créditos: el precio se indica antes, para que el asistente pueda consultarte.
Haz tu primera llamada a la API
Crea una clave y recarga saldo en la plataforma de la API — te lleva un minuto.
Refinamiento de geometría — Powered by Hi3D 1.0

