3D Model Generation¶

MDU generates 3D models using two AI providers: Tripo3D and Meshy.

Endpoints¶

Method	Path	Auth	Description
POST	`/api/generate-model`	Required	Tripo3D generation
POST	`/api/check-model-task`	Required	Poll Tripo3D task
POST	`/api/generate-model-meshy`	Required	Meshy generation
POST	`/api/check-meshy-task`	Required	Poll Meshy task
POST	`/api/refine-model-meshy`	Required	Meshy PBR refine
POST	`/api/generate-rpg-map`	Required	DALL-E 3 map generation
GET	`/api/proxy-model`	-	CORS proxy for GLB files

AI Provider Routing¶

Input	Provider	Mode
Text only	Tripo3D	`text_to_model`
Single image	Tripo3D	`image_to_model`
Multiple images	Tripo3D	`multiview_to_model`
Text + style	Meshy	`text-to-3d` (preview)
Single image (Meshy)	Meshy	`image-to-3d`
Refine preview	Meshy	`text-to-3d` (refine)

Prompt Optimization¶

Before calling the AI provider, text-only requests pass through Flow 1 (Prompt Optimizer) which uses GPT-4o to:

Enhance the prompt for better 3D generation
Select the optimal provider (Tripo vs Meshy)
Add miniature-specific details (pose, scale, detail level)

Generate Model (Tripo3D)¶

# Text-to-3D
POST /api/generate-model
Authorization: Bearer <token>

{ "prompt": "a medieval dwarf warrior with an axe" }

# Image-to-3D
{ "image_url": "https://...", "prompt": "a red dragon" }

# Multiview
{ "multiview_urls": ["https://front.png", "https://side.png"] }

Response:

{ "task_id": "abc123" }

Warning

Never send model_version in Tripo requests — it causes error 2017.

Check Task Status¶

POST /api/check-model-task
Authorization: Bearer <token>

{ "task_id": "abc123" }

Response (success):

{
  "status": "success",
  "model_url": "https://api.tripo3d.ai/...",
  "task_id": "abc123"
}

Status values: queued, running, success, failed

Generate Model (Meshy)¶

# Text-to-3D
POST /api/generate-model-meshy
Authorization: Bearer <token>

{ "prompt": "a goblin rogue", "art_style": "realistic" }

# Image-to-3D
{ "image_url": "https://..." }

Note

Meshy image-to-3D uses API v1 (/openapi/v1/image-to-3d). Text-to-3D uses v2 (/openapi/v2/text-to-3d). There is no v2 for image-to-3D.

RPG Map Generation¶

POST /api/generate-rpg-map
Authorization: Bearer <token>

{
  "prompt": "ancient forest with hidden temple",
  "map_type": "battle_map",
  "style": "parchment"
}

Valid map types: battle_map, world_map, city, dungeon

Valid styles: parchment, hand_drawn, painterly, realistic, top_down, isometric

Model Proxy¶

CORS proxy for loading GLB files from AI providers in the browser:

GET /api/proxy-model?url=<encoded_url>

Allowed domains: tripo3d.ai, meshy.ai and their subdomains.

Includes SSRF protection: blocks private IPs, localhost, and link-local addresses.

Database Storage¶

Generated models are stored in the model_generations table:

Column	Type	Description
`id`	UUID	Primary key
`user_id`	UUID	Owner
`task_id`	TEXT	Provider task ID
`prompt`	TEXT	Original prompt
`provider`	TEXT	`tripo3d`, `meshy`, or `meshy_image`
`model_url`	TEXT	GLB download URL
`status`	TEXT	`pending`, `running`, `completed`, `failed`
`is_public`	BOOLEAN	Gallery visibility

Usage Limits¶

Generation counts are enforced per subscription plan:

Plan	Generations/month
Free	1
Starter	10
Pro	30

Check current usage via GET /api/usage.