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

    Inicie uma geração

    POST/generate/cloud/ultra

    Envie uma foto no campo multipart file. A resposta traz um task_id.

  3. 3

    Consulte a tarefa

    GET/task/{task_id}/status

    A cada poucos segundos, até que status seja done; aí a resposta traz o model_id.

  4. 4

    Baixe

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

    O 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": "…"}}
Statusdetail.errorSignificado
400invalid_image_urlimage_url_unreachableimage_url_too_largeimage_url_not_imageA 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.
401invalid_api_keyA chave está ausente, incorreta ou revogada.
402insufficient_balancemonthly_limit_reachedkey_limit_reachedSaldo de API insuficiente ou limite mensal (da conta ou da chave) atingido.
403subscription_requiredsession_requiredExige uma sessão conectada no site ou um plano para baixar um modelo feito no site.
404feature_offNão encontrado ou ainda indisponível para você.
409file_not_readyO arquivo do modelo ainda não está pronto.
409idempotency_key_reusedidempotency_in_progressA Idempotency-Key já foi usada com outra requisição, ou a primeira requisição com ela ainda está em andamento.
429rate_limitedtoo_many_jobsLimite 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.

Preço da API por modelo gerado, em dólares americanos
VersãoUma foto2–4 vistas
Wandy 1/generate/cloud/fastUS$ 0,09US$ 0,24
Wandy 1.1/generate/cloudUS$ 0,15US$ 0,27
Wandy 2/generate/cloud/ultraUS$ 0,18US$ 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.

Ver preços da API

Endpoints

A API pública em uma tabela. Todas as rotas usam a mesma chave Bearer.

Geração

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

Segredos de webhook e evento de teste
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/mcp

Adicione 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

  1. Nas configurações de conectores do app, adicione um conector personalizado com a URL do servidor acima.
  2. Entre com Wandy3D quando o app pedir e autorize a conexão.
  3. 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

  1. Crie uma chave na plataforma de API e adicione saldo à sua API.
  2. Adicione o servidor com a chave no cabeçalho Authorization — exemplos abaixo.
  3. 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 desenho
  • generate_from_textCriar um modelo 3D a partir de uma descrição
  • get_taskAcompanhar uma geração e mostrar o modelo pronto
  • list_modelsNavegar pela sua biblioteca
  • get_modelAbrir um dos seus modelos
  • export_modelBaixar GLB, FBX, OBJ, USDZ ou STL
  • check_printVerificar um modelo para impressão 3D, grátis: veredito, tamanho impresso, material, tempo de impressão, reparos
  • make_low_polyCriar uma versão Low Poly para jogos, AR e web
  • rig_modelFazer o rig de um modelo com esqueleto e animações prontas
  • list_animationsListar os clipes de animação de um modelo com rig
  • animate_faceAnimar o rosto de um modelo: formas de expressão e clipes prontos — sorrir, piscar, falar e mais
  • make_craftTransformar um modelo em papercraft, camadas para corte a laser, um kit de blocos ou um brinquedo flexi
  • get_creditsVer seu saldo e os preços: créditos, ou seu saldo da API quando você conecta com uma chave
  • browse_galleryVer modelos de exemplo no visualizador 3D, sem precisar entrar
  • get_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.

Obter chave de API

Refinamento de geometria — Powered by Hi3D 1.0