Wandy3D API
Kodundan, oyun motorundan ya da yapay zekâ ajanından 3D model oluştur
Bir fotoğraf, birkaç açı ya da tek bir cümle gönder, dokulu bir 3D model al. Sonra dışa aktar, baskıya hazırla, quad'larla remesh uygula, rig ekle ya da oyun motorun için paketle. Stüdyodakiyle aynı işlem hattı, sade HTTPS üzerinden.
Model başına en az $0,09 (Wandy 1) · Wandy 2 $0,18
$2,00 ücretsiz deneme — ilk API anahtarınla yaklaşık 11 Wandy 2 modeli ya da 22 Wandy 1 modeli.
- Süresi hiç dolmayan ön ödemeli bakiye · abonelik yok
- Bearer anahtarıyla kimlik doğrulama
- Anahtar başına dakikada 60 istek
- HTTPS üzerinden REST ve JSON
# 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>"}, …}Hızlı başlangıç
Fotoğraftan GLB dosyasına dört adım.
- 1
Anahtar oluştur
API platformunda, API anahtarları bölümünde; ardından API bakiyeni yükle. Anahtar yalnızca bir kez gösterilir —
WANDY3D_API_KEYgibi bir ortam değişkeninde sakla. - 2
Üretim başlat
POST
/generate/cloud/ultraTek bir fotoğrafı
filemultipart alanı olarak gönder. Yanıtta birtask_idbulunur. - 3
Görevi sorgula
GET
/task/{task_id}/statusstatusdeğeridoneolana kadar birkaç saniyede bir; ardından yanıttamodel_idbulunur. - 4
İndir
GET
/model/{model_id}/export?format=glbGLB, kısa ömürlü bir bağlantıyla hemen yanıt verir. Diğer formatlar önce dönüştürülür — hazır olana kadar aynı URL'yi sorgula.
# 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>"Anahtarlar ve limitler
Her istek, anahtarını Authorization başlığında taşır.
Authorization: Bearer hg_live_…Anahtarlarını gizli tut
Anahtar senin adına hareket eder ve API bakiyeni harcar. Onu sunucundan, betiklerinden veya CI'dan kullan — asla bir web sayfasında ya da mobil uygulamada değil. Sızan bir anahtarı API platformunda iptal et: hemen çalışmayı bırakır.
İstek limiti
Anahtar başına dakikada 60 istek. Limit aşılırsa retry_after ile birlikte 429 yanıtı döner — beklemen gereken saniye sayısı.
En fazla 10 anahtar
Her uygulama veya makine için ayrı bir anahtar kullan; böylece birini diğerlerine dokunmadan iptal edebilirsin.
Hatalar
Hatalar JSON biçimindedir. Çoğu, detail.error içinde sabit bir kod taşır:
{"detail": {"error": "rate_limited", "retry_after": <seconds>, "message": "…"}}| Durum | detail.error | Anlamı |
|---|---|---|
| 400 | invalid_image_urlimage_url_unreachableimage_url_too_largeimage_url_not_image | İstek gönderildiği haliyle kullanılamıyor: indiremediğimiz bir görsel bağlantısı, hatalı bir parametre ya da callback URL'si. Hiçbir ücret alınmaz. |
| 401 | invalid_api_key | Anahtar eksik, hatalı veya iptal edilmiş. |
| 402 | insufficient_balancemonthly_limit_reachedkey_limit_reached | API bakiyesi yetersiz ya da aylık limite (hesap veya anahtar) ulaşıldı. |
| 403 | subscription_requiredsession_required | Web sitesinde oturum açman ya da web sitesinde yapılan bir modeli indirmek için bir plan gerekir. |
| 404 | feature_off | Bulunamadı veya henüz sana açık değil. |
| 409 | file_not_ready | Model dosyası henüz hazır değil. |
| 409 | idempotency_key_reusedidempotency_in_progress | Bu Idempotency-Key farklı bir istekle zaten kullanıldı ya da ilk isteği hâlâ çalışıyor. |
| 429 | rate_limitedtoo_many_jobs | İstek limitine ulaşıldı ya da aynı anda çok fazla üretim çalışıyor. |
Fiyatlandırma
Bir modelin ABD doları cinsinden maliyeti, güncel API fiyat listesine göre.
| Sürüm | Tek fotoğraf | 2–4 açı |
|---|---|---|
Wandy 1/generate/cloud/fast | $0,09 | $0,24 |
Wandy 1.1/generate/cloud | $0,15 | $0,27 |
Wandy 2/generate/cloud/ultra | $0,18 | $0,30 |
Her ücretli çağrı, ön ödemeli API bakiyenden ABD doları cinsinden tahsil edilir. Kartla en az $5 yükleyebilirsin: bakiyenin süresi hiç dolmaz, başarısız işler otomatik olarak iade edilir.
API üzerinden oluşturduğun modeller senin: hepsini her formatta ücretsiz indirebilirsin.
Google veya Apple ile giriş yapan yeni hesaplar, ilk API anahtarında $2,00 alır — bir kez, kart gerekmez.
Uç noktalar
Herkese açık API tek tabloda. Tüm rotalar aynı Bearer anahtarını kullanır.
Üretim
| Yöntem | Yol | Ne yapar |
|---|---|---|
| POST | /generate/cloud/ultra | Tek fotoğraftan model, Wandy 2Ücretli |
| POST | /generate/cloud | Tek fotoğraftan model, Wandy 1.1Ücretli |
| POST | /generate/cloud/fast | Tek fotoğraftan model, Wandy 1Ücretli |
| POST | /generate/cloud/multi/ultra | 2–4 açıdan model, Wandy 2Ücretli |
| POST | /generate/cloud/multi | Bir nesnenin 2–4 açısından model, Wandy 1.1Ücretli |
| POST | /generate/cloud/multi/fast | 2–4 açıdan model, Wandy 1Ücretli |
| POST | /generate/text/imagine | Metin promptu → konsept görseliÜcretli |
| POST | /generate/text | Konsept görseli → 3D modelÜcretli |
| POST | /generate/retexture | Fotoğraftan modele yeni dokuÜcretli |
Görevler
| Yöntem | Yol | Ne yapar |
|---|---|---|
| GET | /task/{task_id}/status | Üretimin ilerleyişi |
| GET | /api/generate/eta | Şu an bir üretimin ne kadar sürdüğü |
Kitaplık
| Yöntem | Yol | Ne yapar |
|---|---|---|
| GET | /library | Modellerin, en yeniler önce |
| GET | /model/{model_id} | Tek bir model, GLB bağlantısı ve ne olduğu |
| DELETE | /model/{model_id} | Modeli sil |
| GET | /model/{model_id}/versions | Bir modelin tüm sürümleri ve onlardan oluşturulan dosyalar |
İndirme ve son işlem
| Yöntem | Yol | Ne yapar |
|---|---|---|
| GET | /model/{model_id}/stream | Modelin GLB dosyasıİndirme |
| GET | /model/{model_id}/export | GLB, FBX, OBJ, USDZ, STL veya Draco GLB olarak indirİndirme |
| GET | /model/{model_id}/print | Baskı kontrol raporuyla baskıya hazır STL veya 3MFİndirme |
| GET | /model/{model_id}/retopo | Bake edilmiş dokularla quad remesh veya Low PolyÜcretliİndirme |
| GET | /model/{model_id}/rig | Animasyon klipleriyle otomatik rigÜcretli |
| GET | /model/{model_id}/parts | Modeli parçalara ayırÜcretli |
| GET | /model/{model_id}/gamepack | LOD'lar ve collider'larla oyuna hazır paketÜcretliİndirme |
| GET | /model/{model_id}/make/{kind} | El işi araçları, örneğin kâğıt modelÜcretli |
| GET | /model/{model_id}/outputs/{output_id} | Daha önce oluşturulan bir dosyayı yeniden aç |
| GET | /model/{model_id}/rig/suggest | Hangi rig uygun — ödemeden önce, ücretsiz |
Hesap
| Yöntem | Yol | Ne yapar |
|---|---|---|
| GET | /api/platform/balance | API bakiyen |
| GET | /api/platform/prices | Güncel fiyat listesi |
Her işlemin tüm yanıtları ve hataları, örnekleriyle birlikte OpenAPI belgesinde tiplendirilmiştir. Ondan bir istemci oluştur ya da kodlama ajanına ver.
Bağlantılar ve yeniden denemeler
Dosya yüklemek yerine bağlantı gönder ve bir isteği iki kez ödemeden tekrarla.
Bağlantıyla fotoğraf
Her fotoğraf rotası image_url içeren JSON da kabul eder; birden fazla açı için image_urls. Görseli indirir ve tam olarak yüklenmiş bir dosya gibi işleriz. Bağlantı herkese açık bir adreste https olmalı, dosya ise en fazla 20 MB boyutunda JPEG, PNG veya WebP olmalı. Kullanamadığımız bir bağlantı, hiçbir ücret alınmadan 400 döndürür.
# 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üvenli yeniden denemeler
Ücretli bir POST isteğine Idempotency-Key başlığı ekle. Aynı istek 24 saat içinde yeniden gelirse — bir zaman aşımı, kuyruğundan bir yeniden deneme — aynı task_id ile ilk yanıtı alırsın; hiçbir şey ikinci kez başlatılmaz veya ücretlendirilmez. Aynı anahtar farklı bir istekle 409 döndürür.
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'lar
Sorgulamaya gerek yok: üretimi başlatırken callback_url ekle, bittiğinde sunucuna imzalı tek bir olayı POST ile gönderelim.
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.Olaylar
task.completed — model hazır; id'si, adı ve modele ve GLB dışa aktarımına bağlantılarla. task.failed — iş başarısız oldu ve ücreti API bakiyene geri yüklendi. ping — panelden gönderdiğin bir test.
İmzalı
Her olay Wandy-Signature: t=…,v1=… içerir — v1; zaman damgası, bir nokta ve ham gövdenin, işi başlatan API anahtarının webhook gizli anahtarıyla hesaplanan HMAC-SHA256 değeridir. 5 dakikadan eski olayları reddet.
Yeniden denenir
10 saniye içinde herhangi bir 2xx ile yanıt ver. Diğer her durumda aynı olay id'siyle 3 kez yeniden denenir — 30 sn, 2 dk ve 10 dk sonra — böylece kopyaları kolayca ayıklayabilirsin.
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);Yapay zekâ ajanlarıyla kullan
Wandy3D'yi Claude, ChatGPT, Cursor, VS Code ya da MCP destekli herhangi bir uygulamaya bağla. Sade bir dille 3D model iste: asistan onu Wandy3D hesabında oluşturur ve doğrudan sohbette gösterir.
Sunucu URL'si
https://wandy3d.com/mcpTek tıkla editörüne ekle
Editör açılır ve sunucuyu eklemeden önce sorar. Örnek modellere göz atmak ve fiyatları görmek hemen çalışır. Üretim için önce API anahtarını yapıştır: düğmeler onu editörün ayarlarına taşır.
Anahtar tarayıcında kalır: yalnızca editörünü açan bağlantıya eklenir.
Bağlanmanın iki yolu
Wandy3D ile giriş yap
Claude, ChatGPT ve bağlayıcı destekli diğer sohbet uygulamaları
- Uygulamanın bağlayıcı ayarlarında, yukarıdaki sunucu URL'siyle özel bir bağlayıcı ekle.
- Uygulama istediğinde Wandy3D ile giriş yap, ardından bağlantıya izin ver.
- Bir model iste. Sitedeki fiyatlarla Wandy3D kredilerinle oluşturulur.
API anahtarı kullan
Claude Code, Cursor, VS Code ve kendi betiklerin
- API platformunda bir anahtar oluştur ve API bakiyene yükleme yap.
- Sunucuyu, anahtar
Authorizationbaşlığında olacak şekilde ekle — örnekler aşağıda. - Çağrılar API bakiyenden ABD doları olarak ödenir ve bu yolla oluşturulan modeller ücretsiz indirilir.
claude mcp add --transport http wandy3d \ https://wandy3d.com/mcp \ --header "Authorization: Bearer hg_live_…"hg_live_… yerine API platformundaki bir anahtarı yaz. Cursor ~/.cursor/mcp.json dosyasını, VS Code .vscode/mcp.json dosyasını okur; Authorization başlığı gönderebilen her MCP istemcisi çalışır.
Asistan neler yapabilir
generate_from_imageFotoğraf, render veya çizimden 3D model oluşturgenerate_from_textBir açıklamadan 3D model oluşturget_taskÜretimi takip et ve bitmiş modeli gösterlist_modelsKitaplığına göz atget_modelModellerinden birini açexport_modelGLB, FBX, OBJ, USDZ veya STL indircheck_printModeli 3D baskı için ücretsiz kontrol et: sonuç, baskı boyutu, malzeme, baskı süresi, onarımlarmake_low_polyOyunlar, AR ve web için Low Poly sürüm oluşturrig_modelModele iskelet ve hazır animasyonlarla rig eklelist_animationsRigli bir modelin animasyon kliplerini listeleanimate_faceModelin yüzünü canlandır: ifade şekilleri ve hazır klipler — gülümseme, göz kırpma, konuşma ve dahasımake_craftModeli kâğıt modele, lazer katmanlarına, yapı taşı setine ya da esnek oyuncağa dönüştürget_creditsBakiyeni ve fiyatları gör: krediler ya da anahtarla bağlandığında API bakiyenbrowse_galleryÖrnek modelleri 3D görüntüleyicide gör, giriş gerekmezget_pricesGüncel fiyatları kredi cinsinden gör, giriş gerekmez
Sohbette 3D görüntüleyici
MCP Apps destekli istemcilerde biten modeller doğrudan sohbette etkileşimli bir görüntüleyicide açılır: etrafında döndür, kil görünümüne geç, Wandy3D'de aç. Diğer istemciler bir önizleme görseli ve bağlantı alır.
Fiyatı önce sen görürsün
Wandy3D her ücretli işlemin maliyetini asistana bildirir, böylece harcamadan önce sana sorabilir. Başarısız bir üretimin ücreti iade edilir. Kredilerle oluşturulan modellerin dosyaları bir planla, tek seferlik kilit açmayla ya da kredi karşılığında indirilir: fiyat önceden söylenir, böylece asistan sana sorabilir.
İlk API çağrını yap
API platformunda bir anahtar oluştur ve bakiye yükle — bir dakika sürer.
Geometri iyileştirme — Powered by Hi3D 1.0

