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

    Inicia una generación

    POST/generate/cloud/ultra

    Envía una foto en el campo multipart file. La respuesta incluye un task_id.

  3. 3

    Consulta la tarea

    GET/task/{task_id}/status

    Cada pocos segundos, hasta que status sea done; entonces la respuesta incluye el model_id.

  4. 4

    Descarga

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

    GLB 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": "…"}}
Estadodetail.errorSignificado
400invalid_image_urlimage_url_unreachableimage_url_too_largeimage_url_not_imageLa 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.
401invalid_api_keyFalta la clave, es incorrecta o fue revocada.
402insufficient_balancemonthly_limit_reachedkey_limit_reachedNo hay saldo de API suficiente o se alcanzó un límite mensual (de la cuenta o de la clave).
403subscription_requiredsession_requiredRequiere una sesión iniciada en el sitio web, o un plan para descargar un modelo creado en el sitio web.
404feature_offNo encontrado, o aún no está disponible para ti.
409file_not_readyEl archivo del modelo aún no está listo.
409idempotency_key_reusedidempotency_in_progressLa Idempotency-Key ya se usó con otra solicitud, o su primera solicitud aún está en curso.
429rate_limitedtoo_many_jobsSe 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.

Precio de la API por modelo generado, en dólares estadounidenses
VersiónUna foto2–4 vistas
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$

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.

Ver precios de la API

Endpoints

La API pública en una tabla. Todas las rutas usan la misma clave Bearer.

Generar

MétodoRutaQué 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étodoRutaQué 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étodoRutaQué 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étodoRutaQué 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étodoRutaQué 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.

Secretos de webhook y evento de prueba
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/mcp

Añá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

  1. En la configuración de conectores de la app, añade un conector personalizado con la URL del servidor de arriba.
  2. Inicia sesión con Wandy3D cuando la app te lo pida y luego autoriza la conexión.
  3. 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

  1. Crea una clave en la plataforma de la API y recarga tu saldo de la API.
  2. Añade el servidor con la clave en el encabezado Authorization — ejemplos abajo.
  3. 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 dibujo
  • generate_from_textCrear un modelo 3D a partir de una descripción
  • get_taskSeguir una generación y mostrar el modelo terminado
  • list_modelsExplorar tu biblioteca
  • get_modelAbrir uno de tus modelos
  • export_modelDescargar GLB, FBX, OBJ, USDZ o STL
  • check_printRevisar un modelo para impresión 3D, gratis: veredicto, tamaño impreso, material, tiempo de impresión, reparaciones
  • make_low_polyCrear una versión Low Poly para juegos, AR y la web
  • rig_modelAñadir a un modelo un esqueleto y animaciones listas para usar
  • list_animationsVer las animaciones de un modelo con rig
  • animate_faceAnimar la cara de un modelo: formas de expresión y animaciones listas — sonreír, parpadear, hablar y más
  • make_craftConvertir un modelo en papercraft, capas para corte láser, un set de bloques o un juguete flexi
  • get_creditsConsultar tu saldo y los precios: créditos, o tu saldo de la API si te conectas con una clave
  • browse_galleryVer modelos de ejemplo en el visor 3D, sin iniciar sesión
  • get_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.

Obtener una clave de API

Refinamiento de geometría — Powered by Hi3D 1.0