{"_id":"@3dcade/sdk","name":"@3dcade/sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@3dcade/sdk","version":"1.0.0","description":"Official 3Dcade SDK & CLI — text-to-3D generation, embeddable viewers, scenes, and marketplace API for Node.js","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"bin":{"3dcade":"dist/cli.js"},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts --clean --tsconfig tsconfig.json && tsup src/cli.ts --format cjs --no-splitting --clean false --tsconfig tsconfig.json --out-dir dist && node -e \"const fs=require('fs');fs.chmodSync('dist/cli.js',0o755)\"","dev":"tsup src/index.ts --format cjs,esm --dts --watch --tsconfig tsconfig.json","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["3dcade","3d","ai","generative-ai","text-to-3d","3d-models","sdk","cli","solana","nft","metaverse","meshy","glb"],"author":{"name":"3Dcade","email":"team@3dcade.studio"},"license":"MIT","dependencies":{"dotenv":"^16.5.0"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.5.1","typescript":"^5.9.3"},"engines":{"node":">=18"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/3dcade/sdk.git"},"homepage":"https://3dcade.studio","funding":"https://3dcade.studio","bugs":{"url":"https://github.com/3dcade/sdk/issues"},"_id":"@3dcade/sdk@1.0.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-nWtohJNyVyPxwDgGfpfew21wp1nzlQI3fNdZci4h403GSUPhyDvKWysudeX6GwEbnpnzUfP6DP8SELIG92jeGw==","shasum":"f81e524e16910a7cf7219312df9c514d5ed6592b","tarball":"https://registry.npmjs.org/@3dcade/sdk/-/sdk-1.0.0.tgz","fileCount":8,"unpackedSize":93855,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICGGFiaFoTV3PjGE54ESzBWD0mxzdbXmAgc/qUVYhqv2AiEA0HWX8A7i1oB5DUYOvQfkGkketqnLgwlMsOsi8NyOE2E="}]},"_npmUser":{"name":"3dcade","email":"support@3dcade.studio"},"directories":{},"maintainers":[{"name":"3dcade","email":"support@3dcade.studio"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.0_1782526089442_0.22659549524333"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-27T02:08:09.132Z","1.0.0":"2026-06-27T02:08:09.607Z","modified":"2026-06-27T02:08:09.809Z"},"maintainers":[{"name":"3dcade","email":"support@3dcade.studio"}],"description":"Official 3Dcade SDK & CLI — text-to-3D generation, embeddable viewers, scenes, and marketplace API for Node.js","homepage":"https://3dcade.studio","keywords":["3dcade","3d","ai","generative-ai","text-to-3d","3d-models","sdk","cli","solana","nft","metaverse","meshy","glb"],"repository":{"type":"git","url":"git+https://github.com/3dcade/sdk.git"},"author":{"name":"3Dcade","email":"team@3dcade.studio"},"bugs":{"url":"https://github.com/3dcade/sdk/issues"},"license":"MIT","readme":"# @3dcade/sdk\n\n**Create, animate, embed, buy and sell 3D assets — from your terminal or Node.js app.**\n\nOfficial JavaScript / TypeScript SDK and CLI for the [3Dcade](https://3dcade.studio) API. Turn text prompts into web-ready `.glb` models in seconds, embed them anywhere, and tap into scenes, marketplace, and advanced Meshy generation.\n\n[![npm version](https://img.shields.io/npm/v/@3dcade/sdk?color=00d4ff&label=npm)](https://www.npmjs.com/package/@3dcade/sdk)\n[![npm downloads](https://img.shields.io/npm/dm/@3dcade/sdk?color=00d4ff)](https://www.npmjs.com/package/@3dcade/sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)\n\n**Links:** [Website](https://3dcade.studio) · [Twitter / X](https://x.com/3Dcadestudio) · [npm @3dcade](https://www.npmjs.com/~3dcade)\n\n---\n\n## Features\n\n- **Text-to-3D** — generate `.glb` models from a prompt (`realistic`, `lowpoly`, `toon`)\n- **CLI** — `3dcade generate`, `download`, `embed`, `list`, and more from any terminal\n- **TypeScript-first** — full types, ESM + CJS, Node.js 18+\n- **Advanced Meshy API** — text/image-to-3D, retexture, rig, animate\n- **Scenes & marketplace** — create scenes, browse gallery, list and purchase assets\n- **Embeddable viewer** — get iframe HTML and viewer URLs for any ready model\n\n---\n\n## Table of Contents\n\n- [Install](#install)\n- [Get an API Key](#get-an-api-key)\n- [Quick Start — CLI](#quick-start--cli)\n- [CLI Commands](#cli-commands)\n- [Quick Start — SDK](#quick-start--sdk)\n- [SDK API Reference](#sdk-api-reference)\n  - [Constructor](#constructor)\n  - [Text-to-3D (Simple)](#text-to-3d-simple)\n  - [Advanced Generation (Meshy)](#advanced-generation-meshy)\n  - [Scenes](#scenes)\n  - [Community & Gallery](#community--gallery)\n  - [Marketplace](#marketplace)\n  - [Account & Payments](#account--payments)\n- [Error Handling](#error-handling)\n- [Environment Variables](#environment-variables)\n- [Troubleshooting](#troubleshooting)\n\n---\n\n## Install\n\n### Global (for the CLI)\n\n```bash\nnpm install -g @3dcade/sdk\n# or\npnpm add -g @3dcade/sdk\n# or\nyarn global add @3dcade/sdk\n```\n\n### Local (for the SDK in your project)\n\n```bash\nnpm install @3dcade/sdk\n# or\npnpm add @3dcade/sdk\n```\n\n---\n\n## Get an API Key\n\n1. Sign in at **[3dcade.studio](https://3dcade.studio)**\n2. Open **Developer → API Keys**\n3. Click **New key**, copy it\n\n---\n\n## Quick Start — CLI\n\n**Step 1.** Create a `.env` file in any directory:\n\n```bash\necho \"THREEDCADE_API_KEY=3dc_live_YOUR_KEY_HERE\" > .env\n```\n\n**Step 2.** Generate your first model:\n\n```bash\n# Generate and wait for it to finish\n3dcade generate \"a low poly dragon\" --style lowpoly --wait\n\n# Output:\n# ✓ Job created! Model ID: abc123xyz\n# ✓ Model is ready!\n#   ID              abc123xyz\n#   GLB URL         https://cdn.3dcade.studio/models/abc123xyz.glb\n#   Viewer          https://3dcade.studio/viewer/abc123xyz\n```\n\n**Step 3.** Download the `.glb` file:\n\n```bash\n3dcade download abc123xyz --output dragon.glb\n# ✓ Saved: /your/dir/dragon.glb\n```\n\n---\n\n## CLI Commands\n\n| Command | Description |\n|---|---|\n| `3dcade generate \"<prompt>\"` | Generate a 3D model from a text prompt |\n| `3dcade status <id>` | Check the status of a model |\n| `3dcade list` | List all your models |\n| `3dcade download <id>` | Download a model's `.glb` file |\n| `3dcade embed <id>` | Get the viewer URL + iframe HTML |\n| `3dcade me` | Show your account info and usage limits |\n| `3dcade health` | Check API connectivity |\n| `3dcade help` | Show full help |\n\n### `generate` options\n\n| Flag | Default | Description |\n|---|---|---|\n| `--style` | `realistic` | Art style: `realistic`, `lowpoly`, `toon` |\n| `--wait` | `false` | Block until the model is ready |\n| `--output <file>` | — | Also download `.glb` to this path when `--wait` is used |\n\n### `list` options\n\n| Flag | Default | Description |\n|---|---|---|\n| `--status` | — | Filter: `pending`, `ready`, `failed` |\n| `--limit` | `20` | Number of results per page |\n| `--page` | `1` | Page number |\n\n### `download` options\n\n| Flag | Default | Description |\n|---|---|---|\n| `--output <file>` | `<id>.glb` | Output file path |\n\n---\n\n## Quick Start — SDK\n\n```ts\nimport ThreeDcadeClient from \"@3dcade/sdk\";\n\nconst client = new ThreeDcadeClient(process.env.THREEDCADE_API_KEY!);\n\n// One-shot: generate + wait for completion\nconst model = await client.generateAndWait(\"a futuristic spaceship\", \"realistic\", {\n  onProgress: (m) => console.log(`Status: ${m.status} — ID: ${m.id}`),\n});\n\nconsole.log(model.glb_url);    // https://... .glb file URL\nconsole.log(model.viewer_url); // https://... embeddable viewer URL\n```\n\n### With `.env` via `dotenv`\n\n```ts\nimport \"dotenv/config\"; // loads .env automatically\nimport ThreeDcadeClient from \"@3dcade/sdk\";\n\nconst client = new ThreeDcadeClient(process.env.THREEDCADE_API_KEY!);\n```\n\n### CommonJS\n\n```js\nconst { ThreeDcadeClient } = require(\"@3dcade/sdk\");\n\nconst client = new ThreeDcadeClient(process.env.THREEDCADE_API_KEY);\n```\n\n---\n\n## SDK API Reference\n\n### Constructor\n\n```ts\nnew ThreeDcadeClient(apiKey: string, options?: { baseUrl?: string })\n```\n\n| Param | Type | Required | Description |\n|---|---|---|---|\n| `apiKey` | `string` | ✅ | Your `3dc_live_...` API key |\n| `options.baseUrl` | `string` | ❌ | Override base URL (default: `https://3dcade.studio/api`) |\n\n---\n\n### Text-to-3D (Simple)\n\n#### `client.generate(prompt, style?)`\n\nStart a generation. Returns immediately with a task ID.\n\n```ts\nconst result = await client.generate(\"a red sports car\", \"realistic\");\n// result.id       — use to poll\n// result.poll_url — polling URL\n```\n\n| Param | Type | Default | Description |\n|---|---|---|---|\n| `prompt` | `string` | required | Text description (max 300 chars) |\n| `style` | `GenerationStyle` | `\"realistic\"` | `\"realistic\"` \\| `\"lowpoly\"` \\| `\"toon\"` |\n\n---\n\n#### `client.waitForModel(id, options?)`\n\nPoll until the model is `ready` or `failed`.\n\n```ts\nconst model = await client.waitForModel(\"abc123\", {\n  intervalMs: 3000,\n  timeoutMs: 300_000,\n  onProgress: (m) => console.log(m.status),\n});\n```\n\n| Option | Default | Description |\n|---|---|---|\n| `intervalMs` | `3000` | Polling interval in milliseconds |\n| `timeoutMs` | `300000` | Maximum wait time in milliseconds |\n| `onProgress` | — | Called on every poll with the current `Model` |\n\n---\n\n#### `client.generateAndWait(prompt, style?, options?)`\n\nShorthand: generate + wait. Returns the finished `Model`.\n\n```ts\nconst model = await client.generateAndWait(\"a castle on a hill\", \"realistic\");\n```\n\n---\n\n#### `client.getModel(id)`\n\nFetch a model by ID.\n\n```ts\nconst model = await client.getModel(\"abc123\");\nconsole.log(model.status); // \"pending\" | \"ready\" | \"failed\"\n```\n\n---\n\n#### `client.listModels(options?)`\n\nList models for this API key.\n\n```ts\nconst { data, pagination } = await client.listModels({\n  page: 1,\n  limit: 20,\n  status: \"ready\",\n});\n```\n\n---\n\n#### `client.getEmbed(id)`\n\nGet embed data for a ready model.\n\n```ts\nconst embed = await client.getEmbed(\"abc123\");\nconsole.log(embed.iframe_html);  // ready-to-paste <iframe>\nconsole.log(embed.viewer_url);   // URL to the 3D viewer\nconsole.log(embed.glb_url);      // direct .glb download link\n```\n\n---\n\n#### `client.deleteModel(id)`\n\nDelete a model.\n\n```ts\nawait client.deleteModel(\"abc123\");\n```\n\n---\n\n### Advanced Generation (Meshy)\n\nThese use your **advanced daily quota** and return a `MeshyTask`.\n\n#### `client.textTo3d(input)`\n\n```ts\nconst task = await client.textTo3d({\n  prompt: \"a medieval knight\",\n  art_style: \"realistic\",\n  enable_pbr: true,\n});\nconst finished = await client.waitForMeshyTask(task.task_id, {\n  onProgress: (t) => console.log(`${t.status} — ${t.progress}%`),\n});\nconsole.log(finished.model_urls?.glb);\n```\n\n#### `client.imageTo3d(input)`\n\n```ts\nconst task = await client.imageTo3d({\n  image_url: \"https://example.com/my-image.png\",\n  enable_pbr: true,\n});\n```\n\n#### `client.retexture(input)`\n\nRetexture an existing model with a new style prompt.\n\n```ts\nconst task = await client.retexture({\n  model_url: \"https://cdn.../model.glb\",\n  prompt: \"rusty iron armor\",\n});\n```\n\n#### `client.rig(input)` & `client.animate(input)`\n\n```ts\nconst rigTask = await client.rig({ model_url: \"https://cdn.../model.glb\" });\nconst animTask = await client.animate({\n  model_url: \"https://cdn.../model.glb\",\n  prompt: \"walking cycle\",\n});\n```\n\n#### `client.waitForMeshyTask(taskId, options?)`\n\nPoll a Meshy task until `SUCCEEDED` or `FAILED`.\n\n```ts\nconst result = await client.waitForMeshyTask(task.task_id, {\n  intervalMs: 5000,\n  timeoutMs: 600_000,\n  onProgress: (t) => console.log(`${t.status} ${t.progress ?? 0}%`),\n});\n```\n\n---\n\n### Scenes\n\n```ts\n// List scenes\nconst scenes = await client.listScenes({ page: 1, limit: 20 });\n\n// Create\nconst scene = await client.createScene({ name: \"My Scene\", config: { ... } });\n\n// Get / Update / Delete\nawait client.getScene(scene.id);\nawait client.updateScene(scene.id, { name: \"Updated\" });\nawait client.deleteScene(scene.id);\n\n// Public embed (no auth needed)\nconst pub = await client.getPublicScene(scene.id);\n\n// Snapshots\nconst snaps = await client.getSceneSnapshots(scene.id);\n\n// Like\nawait client.toggleSceneLike(scene.id);\n```\n\n---\n\n### Community & Gallery\n\n```ts\n// Public gallery\nconst gallery = await client.getGallery({ sort: \"trending\", limit: 24 });\n\n// Creator profile\nconst profile = await client.getCreatorProfile(\"wallet_address_here\");\n```\n\n---\n\n### Marketplace\n\n```ts\n// Browse listings\nconst listings = await client.getMarketplace({ sort: \"newest\", limit: 12 });\n\n// Detail + reviews\nconst detail = await client.getListingDetail(\"listing_id\");\n\n// Create a listing\nconst listing = await client.createListing({\n  title: \"Sci-Fi Ship Pack\",\n  price_sol: 0.1,\n  scene_id: \"scene_id\",\n});\n\n// Purchase\nawait client.purchaseListing(listing.id, { transaction_signature: \"sig...\" });\n\n// Review\nawait client.createReview(listing.id, { rating: 5, comment: \"Amazing!\" });\n```\n\n---\n\n### Account & Payments\n\n```ts\n// Your profile + usage limits\nconst me = await client.getMe();\nconsole.log(me.tier);\nconsole.log(me.limits.advanced_used, \"/\", me.limits.advanced_daily);\n\n// SOL prices\nconst prices = await client.getPrices();\n\n// Verify payment / upgrade tier\nconst updated = await client.verifyPayment({\n  transaction_signature: \"...\",\n  tier: \"pro\",\n});\n\n// Purchases & earnings\nconst library   = await client.getPurchases();\nconst earnings  = await client.getEarnings();\n```\n\n---\n\n## Error Handling\n\nAll API errors throw `ThreeDcadeError`:\n\n```ts\nimport ThreeDcadeClient, { ThreeDcadeError } from \"@3dcade/sdk\";\n\nconst client = new ThreeDcadeClient(process.env.THREEDCADE_API_KEY!);\n\ntry {\n  const model = await client.getModel(\"invalid-id\");\n} catch (err) {\n  if (err instanceof ThreeDcadeError) {\n    console.log(err.name);    // \"ThreeDcadeError\"\n    console.log(err.code);    // \"NOT_FOUND\" | \"MISSING_KEY\" | \"TIMEOUT\" | ...\n    console.log(err.message); // Human-readable description\n    console.log(err.status);  // HTTP status code (e.g. 404)\n  }\n}\n```\n\n### Common Error Codes\n\n| Code | Status | Meaning |\n|---|---|---|\n| `MISSING_KEY` | — | `apiKey` was empty or not provided |\n| `INVALID_PROMPT` | — | Prompt is empty or over 300 chars |\n| `NOT_FOUND` | 404 | Model/scene/listing does not exist |\n| `UNAUTHORIZED` | 401 | Invalid or expired API key |\n| `LIMIT_REACHED` | 429 | Daily generation quota exhausted |\n| `GENERATION_FAILED` | — | Model failed during generation |\n| `MESHY_TASK_FAILED` | — | Advanced Meshy task failed or expired |\n| `TIMEOUT` | — | Polling timed out |\n| `REQUEST_FAILED` | varies | Generic HTTP error |\n\n---\n\n## Environment Variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `THREEDCADE_API_KEY` | ✅ | Your `3dc_live_...` API key |\n| `THREEDCADE_BASE_URL` | ❌ | Override the API base URL |\n| `NO_COLOR` | ❌ | Disable CLI color output |\n| `DEBUG` | ❌ | Print full error stack traces in CLI |\n\nThe CLI automatically reads `.env` from the **current working directory** — no extra setup needed.\n\n---\n\n## Troubleshooting\n\n### `command not found: 3dcade`\n\nYou installed locally, not globally. Either:\n```bash\nnpm install -g @3dcade/sdk        # install globally\n# OR use npx:\nnpx @3dcade/sdk generate \"prompt\"\n```\n\n### `THREEDCADE_API_KEY is not set`\n\nCreate a `.env` file in the directory where you run the command:\n```bash\necho \"THREEDCADE_API_KEY=3dc_live_YOUR_KEY\" > .env\n```\nOr export it in your shell:\n```bash\nexport THREEDCADE_API_KEY=3dc_live_YOUR_KEY\n```\n\n### Model stuck on `pending`\n\nGeneration can take 1–3 minutes. Use `--wait` to block, or poll:\n```bash\n3dcade status <id>\n```\n\n### `LIMIT_REACHED` error\n\nYou've used your daily generation quota. Upgrade your tier at [3dcade.studio](https://3dcade.studio) → Pricing.\n\n### TypeScript: `fetch is not defined`\n\nRequires **Node.js ≥ 18** (which has `fetch` built-in). Check your version:\n```bash\nnode --version  # should be v18.0.0 or higher\n```\n\n---\n\n## REST API (curl reference)\n\n```bash\n# Health check\ncurl https://3dcade.studio/api/v1/health\n\n# Generate\ncurl -X POST https://3dcade.studio/api/v1/generate \\\n  -H \"Authorization: Bearer 3dc_live_YOUR_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\": \"a futuristic spaceship\", \"style\": \"realistic\"}'\n\n# Poll status\ncurl https://3dcade.studio/api/v1/model/TASK_ID \\\n  -H \"Authorization: Bearer 3dc_live_YOUR_KEY\"\n\n# List models\ncurl \"https://3dcade.studio/api/v1/models?page=1&limit=10\" \\\n  -H \"Authorization: Bearer 3dc_live_YOUR_KEY\"\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\n<p align=\"center\">\n  <strong><a href=\"https://3dcade.studio\">3Dcade</a></strong> — The 3D Web<br/>\n  <a href=\"https://3dcade.studio\">3dcade.studio</a> ·\n  <a href=\"https://x.com/3Dcadestudio\">@3Dcadestudio</a> ·\n  <a href=\"https://www.npmjs.com/~3dcade\">npm</a>\n</p>\n","readmeFilename":"README.md","_rev":"1-8941882987b3cc9fae260fb1593f7fce"}