Skip to content

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.

28.1 KB
Raw Blame
"""three.ws Forge client, shared by the Blender add-on, the ComfyUI nodes and the Modly extension.

Single source of truth for the public Forge generation contract
(``api/forge.js`` + ``api/forge-upload.js``). Stdlib-only (``urllib``) so it
runs unmodified inside Blender's bundled Python and inside ComfyUI without
forcing a ``pip install`` into either host.

Public contract this wraps
---------------------------
* ``POST /api/forge``            ``{prompt, aspect_ratio?, path?, tier?, backend?}``  → text→3D
* ``POST /api/forge``            ``{image_urls[], prompt?, path?, tier?, backend?}``  → image→3D
* ``GET  /api/forge?job=<id>``   → poll ``{status, glb_url?, error?, backend?, ...}``
* ``GET  /api/forge?catalog``    → tier/backend/cost matrix
* ``POST /api/forge-upload``     ``{content_type, size_bytes, checksum_sha256?}`` → presigned PUT
* ``POST /api/scene-glb-upload`` ``{content_type, size_bytes}``                 → presigned PUT for a GLB
* ``POST /api/forge?action=rig`` ``{glb_url}``                                  → auto-rig, polled on ``?job=``
* ``POST /api/forge-remesh``     ``{mesh_url, remesh_mode?, operation?, ...}``    → retopology job
* ``GET  /api/forge-remesh?job=`` → poll ``{status, result_url?, face_count?, error?}``
* ``POST /api/avatars/upload``   raw GLB body, bearer ``avatars:write``          → ``{storage_key, ...}``
* ``POST /api/avatars/presign``  ``{size_bytes, content_type, checksum_sha256}``  → presigned PUT (large GLBs)
* ``POST /api/avatars``          ``{name, storage_key, size_bytes, ...}``        → the saved avatar

Generation is auth-free (IP rate-limited, scoped to an anonymous client handle).
The geometry path (Meshy/Tripo) is BYOK: pass ``provider_key`` and it travels as
the ``x-forge-provider-key`` header. Publishing a GLB into an account
(``publish_glb``) is the one authenticated call: it takes an API key from
three.ws/dashboard/api carrying the ``avatars:write`` scope.

This file is vendored byte-for-byte into each plugin package; the canonical copy
lives at ``integrations/_pyclient/three_ws_client.py`` and a drift test keeps the
vendored copies identical.
"""

from __future__ import annotations

import hashlib
import json
import ssl
import time
import urllib.error
import urllib.parse
import urllib.request
import uuid
from typing import Callable, Optional

DEFAULT_BASE_URL = "https://three.ws"
DEFAULT_TIMEOUT = 30.0          # per HTTP request
DEFAULT_POLL_INTERVAL = 2.0     # seconds between job polls
DEFAULT_POLL_TIMEOUT = 300.0    # overall ceiling for a generation

# Mirrors api/_lib/forge-tiers.js so the plugins can present choices without a
# network round-trip. ``get_catalog()`` fetches the live matrix when needed.
TIERS = ("draft", "standard", "high")
PATHS = ("image", "geometry", "sketch")
BACKENDS = (
    "trellis2",
    "hunyuan3d",
    "nvidia",
    "trellis_selfhost",
    "huggingface",
    "trellis",
    "triposg",
    "meshy",
    "tripo",
    "rodin",
    "stability",
    "replicate_byok",
)
ASPECT_RATIOS = ("1:1", "4:3", "3:4", "16:9", "9:16")
AVATAR_VISIBILITIES = ("private", "unlisted", "public")
REMESH_MODES = ("triangle", "quad", "lowpoly")
REMESH_OPERATIONS = ("full", "simplify", "repair", "convert")
REMESH_TEXTURE_SIZES = (512, 1024, 2048)
MAX_SCENE_GLB_BYTES = 200 * 1024 * 1024

# The upload proxy (``/api/avatars/upload``) accepts bodies up to 50 MB and
# canonicalizes humanoid bone names at ingest. Anything larger goes through the
# presigned direct-to-storage path instead.
MAX_PROXY_UPLOAD_BYTES = 50 * 1024 * 1024
MAX_AVATAR_BYTES = 500 * 1024 * 1024

_CONTENT_TYPE_BY_EXT = {
    "png": "image/png",
    "jpg": "image/jpeg",
    "jpeg": "image/jpeg",
    "webp": "image/webp",
}


def _ssl_context() -> ssl.SSLContext:
    """CA bundle for HTTPS. Embedded Pythons (Blender, Modly, python.org macOS
    builds) often ship without system roots, so prefer certifi when present."""
    try:
        import certifi  # type: ignore

        return ssl.create_default_context(cafile=certifi.where())
    except ImportError:
        return ssl.create_default_context()


_SSL = _ssl_context()


def _urlopen(req: urllib.request.Request, timeout: float):
    if req.full_url.startswith("https://"):
        return urllib.request.urlopen(req, timeout=timeout, context=_SSL)
    return urllib.request.urlopen(req, timeout=timeout)


class ThreeWSError(Exception):
    """A Forge request failed. ``message`` is safe to show a user."""

    def __init__(self, message: str, *, code: str = "", status: int = 0):
        super().__init__(message)
        self.message = message
        self.code = code
        self.status = status


def content_type_for_path(path: str) -> str:
    """Map an image filename to the content-type Forge accepts, or raise."""
    ext = path.rsplit(".", 1)[-1].lower() if "." in path else ""
    ct = _CONTENT_TYPE_BY_EXT.get(ext)
    if not ct:
        raise ThreeWSError(
            f"Unsupported image type '.{ext}'. Use PNG, JPEG, or WebP.",
            code="invalid_content_type",
        )
    return ct


class ThreeWSClient:
    """Submit, poll, and download three.ws Forge generations.

    Parameters
    ----------
    base_url:       deployment origin (default ``https://three.ws``).
    provider_key:   optional Meshy/Tripo key for the BYOK geometry path.
    client_handle:  anonymous handle that scopes creations; generated if omitted.
    timeout:        per-request timeout in seconds.
    """

    def __init__(
        self,
        base_url: str = DEFAULT_BASE_URL,
        *,
        provider_key: Optional[str] = None,
        client_handle: Optional[str] = None,
        timeout: float = DEFAULT_TIMEOUT,
    ):
        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
        self.provider_key = (provider_key or "").strip() or None
        self.client_handle = client_handle or uuid.uuid4().hex
        self.timeout = timeout

    # -- low-level HTTP ------------------------------------------------------

    def _headers(self, extra: Optional[dict] = None) -> dict:
        headers = {
            "accept": "application/json",
            "x-forge-client": self.client_handle,
            "user-agent": "three-ws-plugin/1.0",
        }
        if self.provider_key:
            headers["x-forge-provider-key"] = self.provider_key
        if extra:
            headers.update(extra)
        return headers

    def _request(
        self,
        method: str,
        path: str,
        *,
        body: Optional[dict] = None,
        raw: Optional[bytes] = None,
        headers: Optional[dict] = None,
        timeout: Optional[float] = None,
    ) -> dict:
        url = f"{self.base_url}{path}"
        data = None
        merged = self._headers(headers)
        if body is not None:
            data = json.dumps(body).encode("utf-8")
            merged["content-type"] = "application/json"
        elif raw is not None:
            data = raw
        req = urllib.request.Request(url, data=data, headers=merged, method=method)
        try:
            with _urlopen(req, timeout or self.timeout) as resp:
                payload = resp.read()
        except urllib.error.HTTPError as exc:
            payload = exc.read()
            parsed = _safe_json(payload)
            raise ThreeWSError(
                parsed.get("message") or parsed.get("error") or f"HTTP {exc.code}",
                code=parsed.get("error", ""),
                status=exc.code,
            ) from exc
        except urllib.error.URLError as exc:
            raise ThreeWSError(
                f"Could not reach {self.base_url}: {exc.reason}",
                code="unreachable",
            ) from exc
        return _safe_json(payload)

    # -- catalog -------------------------------------------------------------

    def get_catalog(self) -> dict:
        """Live tier/backend/cost matrix from ``GET /api/forge?catalog``."""
        return self._request("GET", "/api/forge?catalog")

    # -- image upload (image→3D needs a public URL) --------------------------

    def upload_image(self, image_bytes: bytes, content_type: str) -> str:
        """Presign + PUT an image, returning its public URL for image→3D.

        Raises ThreeWSError with actionable guidance if storage is not
        configured on the deployment (the caller may pass a public URL instead).
        """
        if not image_bytes:
            raise ThreeWSError("Image is empty.", code="invalid_size")
        checksum = hashlib.sha256(image_bytes).hexdigest()
        presign = self._request(
            "POST",
            "/api/forge-upload",
            body={
                "content_type": content_type,
                "size_bytes": len(image_bytes),
                "checksum_sha256": checksum,
            },
        )
        return self._put_presigned(presign, image_bytes, content_type, "Image")

    def upload_glb(self, glb_bytes: bytes) -> str:
        """Presign + PUT a binary glTF, returning its public URL.

        Rigging and remeshing take a public mesh URL, so a mesh that exists only
        on the caller's disk goes up through ``/api/scene-glb-upload`` first.
        """
        if not is_glb(glb_bytes):
            raise ThreeWSError("Mesh must be a binary glTF 2.0 (.glb) file.", code="invalid_glb")
        if len(glb_bytes) > MAX_SCENE_GLB_BYTES:
            raise ThreeWSError("Mesh is larger than the 200 MB upload limit.", code="too_large")
        presign = self._request(
            "POST",
            "/api/scene-glb-upload",
            body={"content_type": "model/gltf-binary", "size_bytes": len(glb_bytes)},
        )
        return self._put_presigned(presign, glb_bytes, "model/gltf-binary", "Mesh")

    def _put_presigned(self, presign: dict, data: bytes, content_type: str, label: str) -> str:
        upload_url = presign.get("upload_url")
        public_url = presign.get("public_url")
        if not upload_url or not public_url:
            raise ThreeWSError("Upload presign returned no URL.", code="presign_failed")
        put_headers = presign.get("headers") or {"content-type": content_type}
        put_req = urllib.request.Request(upload_url, data=data, headers=put_headers, method="PUT")
        try:
            with _urlopen(put_req, max(self.timeout, 60)) as resp:
                resp.read()
        except urllib.error.HTTPError as exc:
            raise ThreeWSError(
                f"{label} upload failed (HTTP {exc.code}).", code="upload_failed", status=exc.code
            ) from exc
        except urllib.error.URLError as exc:
            raise ThreeWSError(f"{label} upload failed: {exc.reason}", code="upload_failed") from exc
        return public_url

    # -- submit --------------------------------------------------------------

    def submit_text_to_3d(
        self,
        prompt: str,
        *,
        tier: str = "standard",
        backend: Optional[str] = None,
        path: str = "image",
        aspect_ratio: str = "1:1",
    ) -> dict:
        prompt = (prompt or "").strip()
        if len(prompt) < 3:
            raise ThreeWSError("Describe one subject in at least 3 characters.", code="invalid_prompt")
        body = {"prompt": prompt, "tier": tier, "path": path, "aspect_ratio": aspect_ratio}
        if backend:
            body["backend"] = backend
        return self._submit(body)

    def submit_image_to_3d(
        self,
        image_urls,
        *,
        prompt: str = "",
        tier: str = "standard",
        backend: Optional[str] = None,
        path: str = "image",
    ) -> dict:
        if isinstance(image_urls, str):
            image_urls = [image_urls]
        image_urls = [u for u in image_urls if isinstance(u, str) and u.startswith("https://")]
        if not image_urls:
            raise ThreeWSError("image_to_3d needs at least one public https image URL.", code="invalid_image_urls")
        body = {"image_urls": image_urls, "tier": tier, "path": path}
        if prompt.strip():
            body["prompt"] = prompt.strip()
        if backend:
            body["backend"] = backend
        return self._submit(body)

    def _submit(self, body: dict) -> dict:
        result = self._request("POST", "/api/forge", body=body)
        err = result.get("error")
        if err == "needs_key":
            raise ThreeWSError(
                "This backend (Meshy/Tripo) needs your provider API key. "
                "Set it in the add-on preferences / node input.",
                code="needs_key",
            )
        if err == "backend_unconfigured":
            raise ThreeWSError(
                result.get("message") or "That backend is not configured on this deployment.",
                code="backend_unconfigured",
            )
        if err == "unconfigured":
            raise ThreeWSError(
                result.get("message") or "Generation is not configured on this deployment.",
                code="unconfigured",
            )
        if err:
            raise ThreeWSError(result.get("message") or err, code=err)
        job_id = result.get("job_id")
        if not job_id:
            raise ThreeWSError("Forge returned no job id.", code="no_job")
        return result

    # -- poll ----------------------------------------------------------------

    def poll(
        self,
        job_id: str,
        *,
        on_progress: Optional[Callable[[str, float], None]] = None,
        interval: float = DEFAULT_POLL_INTERVAL,
        timeout: float = DEFAULT_POLL_TIMEOUT,
        should_cancel: Optional[Callable[[], bool]] = None,
        _now: Callable[[], float] = time.monotonic,
        _sleep: Callable[[float], None] = time.sleep,
    ) -> str:
        """Block until the job is done; return its GLB URL.

        ``on_progress(status, elapsed_seconds)`` is called each tick. Raises
        ThreeWSError on failure or timeout. ``should_cancel`` lets a host abort.
        """
        return self._poll_until(
            f"/api/forge?job={urllib.parse.quote(job_id)}",
            "glb_url",
            "Generation",
            on_progress=on_progress,
            interval=interval,
            timeout=timeout,
            should_cancel=should_cancel,
            _now=_now,
            _sleep=_sleep,
        )

    def _poll_until(
        self,
        path: str,
        result_key: str,
        label: str,
        *,
        on_progress: Optional[Callable[[str, float], None]],
        interval: float,
        timeout: float,
        should_cancel: Optional[Callable[[], bool]],
        _now: Callable[[], float],
        _sleep: Callable[[float], None],
    ) -> str:
        start = _now()
        while True:
            if should_cancel and should_cancel():
                raise ThreeWSError(f"{label} cancelled.", code="cancelled")
            elapsed = _now() - start
            if elapsed > timeout:
                raise ThreeWSError(f"{label} timed out after {int(elapsed)}s.", code="timeout")
            try:
                result = self._request("GET", path)
            except ThreeWSError as exc:
                # A 502/503/504 on a poll is a transient upstream hiccup (the
                # remesh worker answers 502 while it cold-starts); keep polling.
                if exc.status in (502, 503, 504):
                    _sleep(interval)
                    continue
                raise
            status = result.get("status") or "running"
            if on_progress:
                on_progress(status, elapsed)
            if status == "done" and result.get(result_key):
                return result[result_key]
            if status == "failed":
                raise ThreeWSError(result.get("error") or f"{label} failed.", code="failed")
            _sleep(interval)

    # -- rig -----------------------------------------------------------------

    def submit_rig(self, glb_url: str) -> dict:
        """Start auto-rigging a public GLB; returns ``{job_id, ...}``."""
        if not _is_web_url(glb_url):
            raise ThreeWSError("Rigging needs a public GLB URL.", code="invalid_glb_url")
        result = self._request("POST", "/api/forge?action=rig", body={"glb_url": glb_url})
        if result.get("error"):
            raise ThreeWSError(result.get("message") or result["error"], code=result["error"])
        if not result.get("job_id"):
            raise ThreeWSError("The rigger returned no job id.", code="no_job")
        return result

    def rig(
        self,
        glb_url: str,
        *,
        on_progress: Optional[Callable[[str, float], None]] = None,
        should_cancel: Optional[Callable[[], bool]] = None,
        poll_timeout: float = 600.0,
        _now: Callable[[], float] = time.monotonic,
        _sleep: Callable[[float], None] = time.sleep,
    ) -> str:
        """Auto-rig a GLB with a humanoid skeleton; return the rigged GLB URL."""
        job = self.submit_rig(glb_url)
        return self._poll_until(
            f"/api/forge?job={urllib.parse.quote(job['job_id'])}",
            "glb_url",
            "Rigging",
            on_progress=on_progress,
            interval=DEFAULT_POLL_INTERVAL,
            timeout=poll_timeout,
            should_cancel=should_cancel,
            _now=_now,
            _sleep=_sleep,
        )

    # -- remesh --------------------------------------------------------------

    def submit_remesh(
        self,
        mesh_url: str,
        *,
        remesh_mode: str = "triangle",
        operation: str = "full",
        target_faces: Optional[int] = None,
        texture_size: int = 1024,
    ) -> dict:
        """Start a remesh/retopology job on a public GLB; returns ``{job_id, ...}``."""
        if not _is_web_url(mesh_url):
            raise ThreeWSError("Remeshing needs a public mesh URL.", code="invalid_mesh_url")
        if remesh_mode not in REMESH_MODES:
            raise ThreeWSError(
                f"remesh_mode must be one of: {', '.join(REMESH_MODES)}.", code="invalid_mode"
            )
        if operation not in REMESH_OPERATIONS:
            raise ThreeWSError(
                f"operation must be one of: {', '.join(REMESH_OPERATIONS)}.", code="invalid_operation"
            )
        if texture_size not in REMESH_TEXTURE_SIZES:
            raise ThreeWSError("texture_size must be 512, 1024 or 2048.", code="invalid_texture_size")
        body = {
            "mesh_url": mesh_url,
            "remesh_mode": remesh_mode,
            "operation": operation,
            "texture_size": texture_size,
            "output_format": "glb",
        }
        if target_faces and int(target_faces) > 0:
            body["target_faces"] = int(target_faces)
        result = self._request("POST", "/api/forge-remesh", body=body)
        if result.get("error"):
            raise ThreeWSError(result.get("message") or result["error"], code=result["error"])
        if not result.get("job_id"):
            raise ThreeWSError("Mesh processing returned no job id.", code="no_job")
        return result

    def remesh(
        self,
        mesh_url: str,
        *,
        remesh_mode: str = "triangle",
        operation: str = "full",
        target_faces: Optional[int] = None,
        texture_size: int = 1024,
        on_progress: Optional[Callable[[str, float], None]] = None,
        should_cancel: Optional[Callable[[], bool]] = None,
        poll_timeout: float = 900.0,
        _now: Callable[[], float] = time.monotonic,
        _sleep: Callable[[float], None] = time.sleep,
    ) -> str:
        """Remesh a GLB on the remesh worker; return the processed GLB URL."""
        job = self.submit_remesh(
            mesh_url,
            remesh_mode=remesh_mode,
            operation=operation,
            target_faces=target_faces,
            texture_size=texture_size,
        )
        return self._poll_until(
            f"/api/forge-remesh?job={urllib.parse.quote(job['job_id'])}",
            "result_url",
            "Mesh processing",
            on_progress=on_progress,
            interval=DEFAULT_POLL_INTERVAL,
            timeout=poll_timeout,
            should_cancel=should_cancel,
            _now=_now,
            _sleep=_sleep,
        )

    # -- download ------------------------------------------------------------

    def download(self, url: str, dest_path: str) -> str:
        """Stream a GLB (or any URL) to ``dest_path``; return the path."""
        req = urllib.request.Request(url, headers={"user-agent": "three-ws-plugin/1.0"})
        try:
            with _urlopen(req, max(self.timeout, 120)) as resp, open(
                dest_path, "wb"
            ) as out:
                while True:
                    chunk = resp.read(64 * 1024)
                    if not chunk:
                        break
                    out.write(chunk)
        except (urllib.error.HTTPError, urllib.error.URLError) as exc:
            raise ThreeWSError(f"Download failed: {exc}", code="download_failed") from exc
        return dest_path

    # -- publish into an account --------------------------------------------

    def publish_glb(
        self,
        glb_bytes: bytes,
        *,
        api_key: str,
        name: str,
        description: str = "",
        visibility: str = "private",
        tags=(),
        source_meta: Optional[dict] = None,
    ) -> dict:
        """Save a GLB into the API key owner's three.ws account; return the avatar.

        The returned dict is the ``avatar`` object from ``POST /api/avatars``
        (``id``, ``name``, ``slug``, ``visibility``, ...). Its page lives at
        ``avatar_page_url(avatar)``. Static meshes are auto-rigged server-side
        when they are humanoid, exactly like a dashboard upload.
        """
        api_key = (api_key or "").strip()
        if not api_key:
            raise ThreeWSError(
                "Publishing needs a three.ws API key with the avatars:write scope. "
                "Create one at three.ws/dashboard/api.",
                code="missing_api_key",
            )
        name = (name or "").strip()[:120] or "Untitled model"
        if visibility not in AVATAR_VISIBILITIES:
            raise ThreeWSError(
                f"visibility must be one of: {', '.join(AVATAR_VISIBILITIES)}.",
                code="invalid_visibility",
            )
        if not is_glb(glb_bytes):
            raise ThreeWSError(
                "That file is not a binary glTF 2.0 (.glb). Export the mesh as GLB first.",
                code="invalid_glb",
            )
        if len(glb_bytes) > MAX_AVATAR_BYTES:
            raise ThreeWSError("GLB is larger than the 500 MB account limit.", code="too_large")

        auth = {"authorization": f"Bearer {api_key}"}
        checksum = hashlib.sha256(glb_bytes).hexdigest()
        slug = slugify(name)
        if len(glb_bytes) <= MAX_PROXY_UPLOAD_BYTES:
            query = urllib.parse.urlencode(
                {"slug": slug, "content_type": "model/gltf-binary", "sha256": checksum}
            )
            stored = self._request(
                "POST",
                f"/api/avatars/upload?{query}",
                raw=glb_bytes,
                headers={**auth, "content-type": "model/gltf-binary"},
                timeout=max(self.timeout, 120),
            )
            storage_key = stored.get("storage_key")
            size_bytes = stored.get("size_bytes") or len(glb_bytes)
            checksum = stored.get("checksum_sha256") or checksum
        else:
            presign = self._request(
                "POST",
                "/api/avatars/presign",
                body={
                    "size_bytes": len(glb_bytes),
                    "content_type": "model/gltf-binary",
                    "checksum_sha256": checksum,
                    "slug": slug,
                },
                headers=auth,
            )
            storage_key = presign.get("storage_key")
            upload_url = presign.get("upload_url")
            if not storage_key or not upload_url:
                raise ThreeWSError("Upload presign returned no URL.", code="presign_failed")
            put_headers = presign.get("headers") or {"content-type": "model/gltf-binary"}
            put_req = urllib.request.Request(
                upload_url, data=glb_bytes, headers=put_headers, method="PUT"
            )
            try:
                with _urlopen(put_req, max(self.timeout, 600)) as resp:
                    resp.read()
            except urllib.error.HTTPError as exc:
                raise ThreeWSError(
                    f"GLB upload failed (HTTP {exc.code}).", code="upload_failed", status=exc.code
                ) from exc
            except urllib.error.URLError as exc:
                raise ThreeWSError(f"GLB upload failed: {exc.reason}", code="upload_failed") from exc
            size_bytes = len(glb_bytes)
        if not storage_key:
            raise ThreeWSError("Upload returned no storage key.", code="upload_failed")

        body = {
            "name": name,
            "storage_key": storage_key,
            "size_bytes": size_bytes,
            "content_type": "model/gltf-binary",
            "checksum_sha256": checksum,
            "visibility": visibility,
            "tags": [t.strip()[:40] for t in tags if isinstance(t, str) and t.strip()][:20],
            "source": "upload",
            "source_meta": dict(source_meta or {}),
        }
        if description.strip():
            body["description"] = description.strip()[:2000]
        created = self._request("POST", "/api/avatars", body=body, headers=auth)
        avatar = created.get("avatar")
        if not isinstance(avatar, dict) or not avatar.get("id"):
            raise ThreeWSError("three.ws did not return the saved model.", code="create_failed")
        return avatar

    def avatar_page_url(self, avatar: dict) -> str:
        """Public page for an avatar returned by ``publish_glb``."""
        return f"{self.base_url}/avatars/{urllib.parse.quote(str(avatar.get('id', '')))}"

    # -- high-level convenience ---------------------------------------------

    def generate_text_to_3d(
        self,
        prompt: str,
        *,
        tier: str = "standard",
        backend: Optional[str] = None,
        path: str = "image",
        aspect_ratio: str = "1:1",
        on_progress: Optional[Callable[[str, float], None]] = None,
        should_cancel: Optional[Callable[[], bool]] = None,
        poll_timeout: float = DEFAULT_POLL_TIMEOUT,
    ) -> str:
        job = self.submit_text_to_3d(
            prompt, tier=tier, backend=backend, path=path, aspect_ratio=aspect_ratio
        )
        return self.poll(
            job["job_id"], on_progress=on_progress, should_cancel=should_cancel, timeout=poll_timeout
        )

    def generate_image_to_3d(
        self,
        image_bytes: bytes,
        content_type: str,
        *,
        prompt: str = "",
        tier: str = "standard",
        backend: Optional[str] = None,
        path: str = "image",
        on_progress: Optional[Callable[[str, float], None]] = None,
        should_cancel: Optional[Callable[[], bool]] = None,
        poll_timeout: float = DEFAULT_POLL_TIMEOUT,
    ) -> str:
        public_url = self.upload_image(image_bytes, content_type)
        job = self.submit_image_to_3d(public_url, prompt=prompt, tier=tier, backend=backend, path=path)
        return self.poll(
            job["job_id"], on_progress=on_progress, should_cancel=should_cancel, timeout=poll_timeout
        )


def is_glb(data: bytes) -> bool:
    """True when ``data`` starts with a well-formed binary glTF 2.0 header."""
    if not isinstance(data, (bytes, bytearray)) or len(data) < 12:
        return False
    magic = bytes(data[0:4])
    version = int.from_bytes(data[4:8], "little")
    length = int.from_bytes(data[8:12], "little")
    return magic == b"glTF" and version == 2 and length == len(data)


def slugify(text: str) -> str:
    """Lowercase ``[a-z0-9_-]`` slug (max 64) that ``/api/avatars`` accepts."""
    out = []
    for ch in (text or "").lower():
        if ch.isascii() and (ch.isalnum() or ch in "-_"):
            out.append(ch)
        elif out and out[-1] != "-":
            out.append("-")
    slug = "".join(out).strip("-_")[:64].strip("-_")
    return slug or "model"


def _is_web_url(url) -> bool:
    """An http(s) URL. The server decides what is publicly reachable (it
    SSRF-checks every mesh URL); this only stops local paths early."""
    return isinstance(url, str) and url.startswith(("https://", "http://"))


def _safe_json(payload: bytes) -> dict:
    try:
        parsed = json.loads(payload.decode("utf-8"))
        return parsed if isinstance(parsed, dict) else {"value": parsed}
    except (ValueError, UnicodeDecodeError):
        return {}