Wandy3D API
Gere modelos 3D a partir do seu código, engine ou agente de IA
Envie uma foto, algumas vistas ou uma frase e receba um modelo 3D texturizado — depois exporte, imprima, faça o remesh em quads, adicione um rig ou prepare para a sua engine de jogo. O mesmo pipeline do estúdio, via HTTPS comum.
A partir de US$ 0,09 por modelo (Wandy 1) · Wandy 2 US$ 0,18
US$ 2,00 grátis para testar — cerca de 11 modelos Wandy 2 ou 22 modelos Wandy 1 na sua primeira chave de API.
- Saldo pré-pago que nunca expira · sem assinatura
- Autenticação por chave Bearer
- 60 requisições por minuto por chave
- REST e JSON via 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>"}, …}Guia rápido
Quatro passos de uma foto até um arquivo GLB.
- 1
Crie uma chave
Na plataforma de API, em Chaves de API, e depois recarregue seu saldo de API. A chave aparece uma única vez — guarde-a em uma variável de ambiente, como
WANDY3D_API_KEY. - 2
Inicie uma geração
POST
/generate/cloud/ultraEnvie uma foto no campo multipart
file. A resposta traz umtask_id. - 3
Consulte a tarefa
GET
/task/{task_id}/statusA cada poucos segundos, até que
statussejadone; aí a resposta traz omodel_id. - 4
Baixe
GET
/model/{model_id}/export?format=glbO GLB responde na hora com um link temporário. Os outros formatos são convertidos primeiro — consulte a mesma URL até ficar pronto.
# 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>"Chaves e limites
Toda requisição leva a sua chave no cabeçalho Authorization.
Authorization: Bearer hg_live_…Mantenha as chaves em segredo
Uma chave age em seu nome e gasta o seu saldo de API. Use-a no seu servidor, em scripts ou no CI — nunca em uma página web ou em um app para celular. Revogue uma chave vazada na plataforma de API: ela para de funcionar na hora.
Limite de requisições
60 requisições por minuto por chave. Acima do limite, a resposta é 429 com retry_after — os segundos de espera.
Até 10 chaves
Use uma por app ou máquina, assim você revoga uma sem mexer nas outras.
Erros
Os erros vêm em JSON. A maioria traz um código estável em detail.error:
{"detail": {"error": "rate_limited", "retry_after": <seconds>, "message": "…"}}| Status | detail.error | Significado |
|---|---|---|
| 400 | invalid_image_urlimage_url_unreachableimage_url_too_largeimage_url_not_image | A requisição não pode ser usada como foi enviada: um link de imagem que não conseguimos baixar, um parâmetro ou URL de callback inválido. Nada é cobrado. |
| 401 | invalid_api_key | A chave está ausente, incorreta ou revogada. |
| 402 | insufficient_balancemonthly_limit_reachedkey_limit_reached | Saldo de API insuficiente ou limite mensal (da conta ou da chave) atingido. |
| 403 | subscription_requiredsession_required | Exige uma sessão conectada no site ou um plano para baixar um modelo feito no site. |
| 404 | feature_off | Não encontrado ou ainda indisponível para você. |
| 409 | file_not_ready | O arquivo do modelo ainda não está pronto. |
| 409 | idempotency_key_reusedidempotency_in_progress | A Idempotency-Key já foi usada com outra requisição, ou a primeira requisição com ela ainda está em andamento. |
| 429 | rate_limitedtoo_many_jobs | Limite de requisições atingido ou gerações demais rodando ao mesmo tempo. |
Preços
Quanto custa um modelo, em dólares americanos, segundo a tabela de preços atual da API.
| Versão | Uma foto | 2–4 vistas |
|---|---|---|
Wandy 1/generate/cloud/fast | US$ 0,09 | US$ 0,24 |
Wandy 1.1/generate/cloud | US$ 0,15 | US$ 0,27 |
Wandy 2/generate/cloud/ultra | US$ 0,18 | US$ 0,30 |
Cada chamada paga é cobrada em dólares americanos do seu saldo de API pré-pago. Recarregue com cartão a partir de $5 — o saldo nunca expira, e tarefas que falham são reembolsadas automaticamente.
Os modelos que você gera pela API são seus para baixar em qualquer formato, de graça.
Contas novas que entram com o Google ou a Apple ganham US$ 2,00 na primeira chave de API — uma única vez, sem cartão.
Endpoints
A API pública em uma tabela. Todas as rotas usam a mesma chave Bearer.
Geração
| Método | Caminho | O que faz |
|---|---|---|
| POST | /generate/cloud/ultra | Modelo a partir de uma foto, Wandy 2Pago |
| POST | /generate/cloud | Modelo a partir de uma foto, Wandy 1.1Pago |
| POST | /generate/cloud/fast | Modelo a partir de uma foto, Wandy 1Pago |
| POST | /generate/cloud/multi/ultra | Modelo a partir de 2–4 vistas, Wandy 2Pago |
| POST | /generate/cloud/multi | Modelo a partir de 2–4 vistas de um objeto, Wandy 1.1Pago |
| POST | /generate/cloud/multi/fast | Modelo a partir de 2–4 vistas, Wandy 1Pago |
| POST | /generate/text/imagine | Prompt de texto → imagem conceitualPago |
| POST | /generate/text | Imagem conceitual → modelo 3DPago |
| POST | /generate/retexture | Nova textura para um modelo a partir de uma fotoPago |
Tarefas
| Método | Caminho | O que faz |
|---|---|---|
| GET | /task/{task_id}/status | Progresso de uma geração |
| GET | /api/generate/eta | Quanto tempo uma geração leva agora |
Biblioteca
| Método | Caminho | O que faz |
|---|---|---|
| GET | /library | Seus modelos, mais recentes primeiro |
| GET | /model/{model_id} | Um modelo, o link do GLB e o que ele é |
| DELETE | /model/{model_id} | Excluir um modelo |
| GET | /model/{model_id}/versions | Todas as versões de um modelo e os arquivos gerados a partir delas |
Downloads e pós-processamento
| Método | Caminho | O que faz |
|---|---|---|
| GET | /model/{model_id}/stream | O arquivo GLB do modeloDownload |
| GET | /model/{model_id}/export | Baixar em GLB, FBX, OBJ, USDZ, STL ou Draco GLBDownload |
| GET | /model/{model_id}/print | STL ou 3MF pronto para impressão, com relatório de verificaçãoDownload |
| GET | /model/{model_id}/retopo | Remesh em quads ou Low Poly com texturas bakeadasPagoDownload |
| GET | /model/{model_id}/rig | Rig automático com clipes de animaçãoPago |
| GET | /model/{model_id}/parts | Dividir um modelo em partesPago |
| GET | /model/{model_id}/gamepack | Pacote pronto para jogos com LODs e colisoresPagoDownload |
| GET | /model/{model_id}/make/{kind} | Artesanato, como papercraftPago |
| GET | /model/{model_id}/outputs/{output_id} | Reabrir um arquivo gerado antes |
| GET | /model/{model_id}/rig/suggest | Qual rig serve — grátis, antes de pagar |
Conta
| Método | Caminho | O que faz |
|---|---|---|
| GET | /api/platform/balance | Seu saldo da API |
| GET | /api/platform/prices | A tabela de preços atualizada |
Todas as respostas e todos os erros de cada operação estão tipados no documento OpenAPI, com exemplos. Gere um cliente a partir dele ou entregue-o ao seu agente de programação.
Links e novas tentativas
Envie um link em vez de fazer upload de um arquivo e repita uma requisição sem pagar duas vezes.
Foto por link
Toda rota de foto também aceita JSON com image_url; para várias vistas, image_urls. Baixamos a imagem e a tratamos exatamente como um upload. O link precisa ser https em um endereço público, e o arquivo, JPEG, PNG ou WebP de até 20 MB. Um link que não conseguimos usar retorna 400 antes de qualquer cobrança.
# 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://."}}Novas tentativas seguras
Adicione um cabeçalho Idempotency-Key a um POST pago. Se a mesma requisição chegar de novo em até 24 horas — um timeout, uma nova tentativa da sua fila —, você recebe a primeira resposta com o mesmo task_id, e nada é iniciado nem cobrado uma segunda vez. A mesma chave com uma requisição diferente retorna 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
Dispense o polling: adicione callback_url ao iniciar uma geração e enviaremos um POST com um evento assinado para o seu servidor quando ela terminar.
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 — o modelo está pronto, com id, nome e links para o modelo e para a exportação GLB. task.failed — a tarefa falhou e a cobrança voltou para o seu saldo da API. ping — um teste que você envia pelo painel.
Assinados
Todo evento traz Wandy-Signature: t=…,v1=… — v1 é o HMAC-SHA256 do timestamp, um ponto e o corpo bruto, usando como chave o segredo de webhook da chave de API que iniciou a tarefa. Rejeite eventos com mais de 5 minutos.
Com novas tentativas
Responda com qualquer 2xx em até 10 segundos. Qualquer outra resposta gera 3 novas tentativas — após 30 s, 2 min e 10 min — com o mesmo id de evento, então é fácil descartar duplicatas.
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);Use com agentes de IA
Conecte o Wandy3D ao Claude, ChatGPT, Cursor, VS Code ou qualquer app compatível com MCP. Peça um modelo 3D com suas próprias palavras: o assistente cria o modelo na sua conta Wandy3D e mostra direto no chat.
URL do servidor
https://wandy3d.com/mcpAdicione ao seu editor com um clique
O editor abre e pergunta antes de adicionar o servidor. Ver modelos de exemplo e consultar preços funciona na hora. Para gerar, cole primeiro sua chave de API: os botões a levam para as configurações do editor.
A chave fica no seu navegador: ela só vai no link que abre o seu editor.
Duas formas de conectar
Entrar com Wandy3D
Claude, ChatGPT e outros apps de chat com conectores
- Nas configurações de conectores do app, adicione um conector personalizado com a URL do servidor acima.
- Entre com Wandy3D quando o app pedir e autorize a conexão.
- Peça um modelo. Ele é criado com seus créditos Wandy3D pelos preços do site.
Usar chave de API
Claude Code, Cursor, VS Code e seus próprios scripts
- Crie uma chave na plataforma de API e adicione saldo à sua API.
- Adicione o servidor com a chave no cabeçalho
Authorization— exemplos abaixo. - As chamadas são pagas em dólares americanos com seu saldo da API, e os modelos criados assim podem ser baixados de graça.
claude mcp add --transport http wandy3d \ https://wandy3d.com/mcp \ --header "Authorization: Bearer hg_live_…"Substitua hg_live_… por uma chave da plataforma de API. O Cursor lê ~/.cursor/mcp.json, o VS Code lê .vscode/mcp.json; qualquer cliente MCP que consiga enviar um cabeçalho Authorization funciona.
O que o assistente pode fazer
generate_from_imageCriar um modelo 3D a partir de uma foto, render ou desenhogenerate_from_textCriar um modelo 3D a partir de uma descriçãoget_taskAcompanhar uma geração e mostrar o modelo prontolist_modelsNavegar pela sua bibliotecaget_modelAbrir um dos seus modelosexport_modelBaixar GLB, FBX, OBJ, USDZ ou STLcheck_printVerificar um modelo para impressão 3D, grátis: veredito, tamanho impresso, material, tempo de impressão, reparosmake_low_polyCriar uma versão Low Poly para jogos, AR e webrig_modelFazer o rig de um modelo com esqueleto e animações prontaslist_animationsListar os clipes de animação de um modelo com riganimate_faceAnimar o rosto de um modelo: formas de expressão e clipes prontos — sorrir, piscar, falar e maismake_craftTransformar um modelo em papercraft, camadas para corte a laser, um kit de blocos ou um brinquedo flexiget_creditsVer seu saldo e os preços: créditos, ou seu saldo da API quando você conecta com uma chavebrowse_galleryVer modelos de exemplo no visualizador 3D, sem precisar entrarget_pricesVer os preços atuais em créditos, sem precisar entrar
Visualizador 3D no chat
Em clientes compatíveis com MCP Apps, os modelos prontos abrem num visualizador interativo direto na conversa: gire, mude para o modo argila, abra no Wandy3D. Os outros clientes recebem uma imagem de prévia e um link.
Você vê o preço antes
O Wandy3D informa ao assistente quanto custa cada ação paga, para que ele confirme com você antes de gastar. Uma geração que falha é reembolsada. Os arquivos de modelos criados com créditos podem ser baixados com um plano, após um desbloqueio avulso ou por créditos: o preço é informado antes, para que o assistente confirme com você.
Faça sua primeira chamada à API
Crie uma chave e adicione saldo na plataforma de API — leva um minuto.
Refinamento de geometria — Powered by Hi3D 1.0

