Text-to-3D

Open Project Working (2).mp4

Generate production-ready 3D models from text prompts using FastAPI, React, Three.js, and AI-powered generation.

Why This Project

Text-to-3D turns a plain language prompt into a downloadable .glb model that can be viewed in-browser with orbit controls and realistic lighting. It is built for demos, rapid prototyping, and content generation workflows.

Highlights

• Multi-strategy generation pipeline with provider fallback.
• FastAPI backend with robust validation and GLB construction.
• React + Three.js frontend with smooth interactive viewing.
• Caching and quality scoring metadata in response headers.
• Image-to-3D endpoint support when Tripo credentials are configured.

Architecture

Browser (React + Three.js)
    |  POST /api/generate { prompt }
    v
FastAPI Backend
    |  prompt planning + AI calls + fallback logic
    v
Generation Providers (Tripo/NVIDIA where configured)
    |  mesh data
    v
Mesh Builder (GLB)
    |  model/gltf-binary response
    v
Browser Viewer (GLTFLoader)

Tech Stack

• Backend: FastAPI, Pydantic, httpx, NumPy, pygltflib
• Frontend: React, Vite, Three.js
• AI/3D Services: Tripo3D, NVIDIA API

Project Structure

text-to-3d/
├── backend/
│   ├── main.py
│   ├── routers/generate.py
│   ├── services/
│   ├── models/
│   └── requirements.txt
├── frontend/
│   ├── src/
│   ├── public/
│   └── package.json
├── project_media/
└── README.md

Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• API credentials in backend/.env

1) Backend

cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt

Create and configure environment file:

cp .env.example .env

Run backend:

uvicorn main:app --reload --port 9000

Backend URLs:

• API base: http://localhost:9000
• Health: http://localhost:9000/api/health
• Docs: http://localhost:9000/docs

2) Frontend

cd frontend
npm install
npm run dev

Frontend URL:

• App: http://localhost:3000

3) One-command Options

From repository root:

• Windows multi-process dev: ./start.ps1
• Windows unified mode: ./start_unified.ps1
• Linux/macOS: ./start.sh

Environment Variables (backend/.env)

Variable	Required	Description
NVIDIA_API_KEY	Optional	NVIDIA key for text generation paths
NVIDIA_API_KEYS	Optional	Comma-separated NVIDIA keys
NVIDIA_API_BASE	Optional	NVIDIA API base URL
NVIDIA_MODELS	Optional	Ordered model preference list
TRIPO_API_KEY	Optional	Primary Tripo API key
TRIPO_API_KEYS	Optional	Comma-separated Tripo keys
TRIPO_CLIENT_ID	Optional	Primary Tripo client ID
TRIPO_CLIENT_IDS	Optional	Comma-separated Tripo client IDs
TRIPO_API_BASE	Optional	Tripo API base URL
TRIPO_MODEL_VERSION	Optional	Tripo model version
ALLOWED_ORIGINS	Optional	CORS whitelist

API Endpoints

POST /api/generate

Request:

{ "prompt": "a glossy luxury sports car" }

Response:

• 200 model/gltf-binary with .glb bytes
• Metadata headers such as X-Mesh-Name, X-Source, X-Quality-Score

POST /api/generate-image

Form-data request for image-to-3D generation.

POST /api/preview

Returns interpreted blueprint/plan before full generation.

GET /api/health

Simple service health status.

Visual and Video Assets

All collected media files are in:

• project_media/

README hero image source:

• frontend/public/images/luxury-car-readme.webp

Troubleshooting

• If frontend fails on port conflict, free port 3000 and restart npm run dev.
• If generation fails from provider limits, backend fallback strategies still return a model when possible.
• If startup scripts fail due to venv path differences, run backend and frontend manually with the commands above.

Apache 2.0 License

This project is licensed under the Apache License 2.0.

• Full text: see LICENSE
• You may use, modify, and distribute this project under Apache-2.0 terms.

Contributing

Contributions are welcome. Open an issue for feature requests or bug reports, and submit a PR with a clear description of changes.