Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
import json
import threading
import uuid
from typing import Optional
from fastapi import APIRouter, BackgroundTasks, File, Form, HTTPException, UploadFile
from pydantic import BaseModel
from routers.generation import (
VALID_REMESH_MODES,
_cancel_events,
_jobs,
_purge_old_jobs,
_run_generation,
cancel_job,
sanitize_collection,
)
from schemas.generation import JobStatus
from services.generator_registry import generator_registry
router = APIRouter(tags=["workflow-runs"])
class WorkflowRunStatus(BaseModel):
run_id: str
status: str
progress: int = 0
step: Optional[str] = None
output_url: Optional[str] = None
error: Optional[str] = None
scene_candidate: Optional[dict] = None
@router.post("/from-image")
async def create_run_from_image(
background_tasks: BackgroundTasks,
image: UploadFile = File(...),
model_id: str = Form("sf3d"),
# Where the result is filed. The legacy /generate/from-image already accepts this; the
# canonical endpoint hardcoded "Default", so a run driven over REST/MCP landed in a folder
# the Library does not index and stayed invisible in the app (#238). Same field, same
# sanitizer, so both surfaces route output the same way.
collection: str = Form("Default"),
params: str = Form("{}"),
):
if not image.content_type or not image.content_type.startswith("image/"):
raise HTTPException(400, "File must be an image")
try:
model_params = json.loads(params)
except (json.JSONDecodeError, TypeError):
model_params = {}
full_params = {
"remesh": "quad",
"enable_texture": False,
"texture_resolution": 1024,
**model_params,
}
# Keep the same request validation as /generate/from-image before filing a job.
if full_params["remesh"] not in VALID_REMESH_MODES:
raise HTTPException(400, "remesh must be 'quad', 'triangle', or 'none'")
collection = sanitize_collection(collection)
try:
generator_registry.get_generator(model_id)
output_kind = generator_registry.get_manifest(model_id).get("output", "mesh")
except ValueError as e:
raise HTTPException(400, str(e))
job_id = str(uuid.uuid4())
image_bytes = await image.read()
_purge_old_jobs()
_jobs[job_id] = JobStatus(job_id=job_id, status="pending", progress=0)
_cancel_events[job_id] = threading.Event()
background_tasks.add_task(
_run_generation, job_id, image_bytes, full_params, collection, output_kind, model_id
)
return {"run_id": job_id, "status": "pending"}
@router.get("/{run_id}", response_model=WorkflowRunStatus)
async def get_run(run_id: str):
job = _jobs.get(run_id)
if not job:
raise HTTPException(404, f"Run {run_id} not found")
scene_candidate = None
if job.status == "done" and job.output_url:
scene_candidate = {"workspace_path": job.output_url.removeprefix("/workspace/")}
return WorkflowRunStatus(
run_id=job.job_id,
status=job.status,
progress=job.progress,
step=job.step,
output_url=job.output_url,
error=job.error,
scene_candidate=scene_candidate,
)
@router.post("/{run_id}/cancel")
async def cancel_run(run_id: str):
return await cancel_job(run_id)