How to Integrate Modly with Other Services via the REST API

Yes, Modly exposes a comprehensive FastAPI-based REST API that allows external services to submit generation jobs, manage workflows, and control core functionality through standard HTTP endpoints with JSON responses and Server-Sent Events (SSE) streaming.

Modly (from the lightningpixel/modly repository) provides a full-featured HTTP interface for integrating with external pipelines. The API follows REST conventions and delegates to a service layer abstraction, making it straightforward to connect automation scripts, web applications, or third-party tools to Modly's 3D generation capabilities.

API Architecture and Available Endpoints

The Modly API is built on FastAPI and organizes functionality into dedicated routers under the /api/v1 base path. Each router handles a specific domain of the application:

• Generation (api/routers/generation.py): Exposes /api/v1/generation endpoints for submitting prompts, streaming results, and retrieving generation metadata.
• Workflow Runs (api/routers/workflow_runs.py): Manages execution lifecycles via /api/v1/workflow-runs for operations like mesh repair and mesh smoothing.
• Model Management (api/routers/model.py): Provides /api/v1/model endpoints for listing available models, downloading weights, and setting active configurations.
• Settings (api/routers/settings.py): Controls Modly configuration through /api/v1/settings, including GPU allocation and temporary directory paths.
• Extensions (api/routers/extensions.py): Handles third-party extension lifecycle via /api/v1/extensions for installation and updates.
• Optimization (api/routers/optimize.py): Triggers model-specific optimizations like quantization at /api/v1/optimize.
• Export (api/routers/export.py): Retrieves generated assets including meshes, textures, and UV maps from /api/v1/export.
• Status & Health (api/routers/status.py): Reports server health, version, and uptime at /api/v1/status.
• Agent (api/routers/agent.py): Provides remote control of the Modly CLI agent process through /api/v1/agent endpoints.

All routes return JSON responses, with Server-Sent Events (SSE) available for streaming generation output in real time.

Authentication and Security

The API supports optional authentication via Bearer tokens. Clients must supply the API key in the Authorization header using the format Authorization: Bearer <token>. Keys are stored in Modly's internal settings and can be generated through the web interface or programmatically via the /api/v1/settings endpoint. When authentication is enabled, all requests to protected endpoints must include this header.

Integration Workflow

External services interact with Modly through a standard four-phase pattern:

1. Discover capabilities: Query /api/v1/status or /api/v1/model to enumerate available models and extensions before submitting work.
2. Submit work: POST generation payloads to /api/v1/generation or workflow configurations to /api/v1/workflow-runs to initiate processing.
3. Track progress: Poll the specific job ID endpoint (e.g., /api/v1/generation/{job_id}) or consume the SSE stream for live updates during long-running operations.
4. Retrieve results: Download final artifacts via /api/v1/export/{job_id} or access the filesystem paths returned in the completion response.

The separation between the router layer (api/routers/) and the service layer (api/services/) ensures that underlying implementations (such as model runners or extension handlers) can be swapped without breaking the external contract.

Implementation Examples

Python Client Implementation

The following Python script demonstrates submitting a prompt with SSE streaming using the requests library:

import requests

API_URL = "http://localhost:8000/api/v1/generation"
HEADERS = {"Authorization": "Bearer your_api_key"}

payload = {
    "model": "stable-diffusion-v1-5",
    "prompt": "A futuristic cityscape at sunset",
    "negative_prompt": "",
    "steps": 30,
    "cfg_scale": 7.5,
    "width": 512,
    "height": 512,
    "stream": True,               # Ask for SSE streaming

}

# Initiate the generation; the response contains a job_id

resp = requests.post(API_URL, json=payload, headers=HEADERS, stream=True)

for line in resp.iter_lines():
    if line:
        # Each line is a JSON chunk with partial output

        data = line.decode("utf-8")
        print("Update:", data)

JavaScript Fetch API

This example triggers a mesh-repair workflow using modern JavaScript fetch:

const apiBase = "http://localhost:8000/api/v1";
const apiKey = "your_api_key";

async function startRepair(meshUrl) {
  const response = await fetch(`${apiBase}/workflow-runs`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      workflow: "mesh-repair",
      inputs: { mesh: meshUrl }
    })
  });

  const { job_id } = await response.json();
  console.log("Workflow started – job ID:", job_id);
  // Poll for status
  const status = await fetch(`${apiBase}/workflow-runs/${job_id}`);
  console.log(await status.json());
}

Command Line with cURL

To list installed extensions from the terminal:

curl -H "Authorization: Bearer $MODLY_API_KEY" \
     http://localhost:8000/api/v1/extensions

Core Implementation Files

Understanding these source files helps when debugging or extending the API:

• api/main.py: The FastAPI application entry point that registers all routers and middleware.
• api/routers/generation.py: Implements /generation endpoints including SSE streaming logic.
• api/routers/workflow_runs.py: Handles workflow execution state machines for operations like mesh repair.
• api/services/generator_registry.py: Central registry for model and extension discovery consumed by the API layer.
• api/services/extension_process.py: Manages spawning and monitoring of external extension processes.
• api/schemas/generation.py: Contains Pydantic models defining request and response validation for generation endpoints.

Summary

• Modly provides a FastAPI-based REST API under /api/v1 with standardized JSON responses.
• Nine specialized routers cover generation, workflows, models, settings, extensions, optimization, export, status, and agent control.
• Authentication uses optional Bearer tokens via the Authorization header.
• Both polling and Server-Sent Events (SSE) are supported for job progress monitoring.
• Any HTTP-capable client (Python, JavaScript, curl, etc.) can integrate with Modly's service layer abstractions.

Frequently Asked Questions

Does Modly require authentication for API access?

No, authentication is optional. When enabled, clients must include a valid API key in the Authorization: Bearer <token> header. The key can be generated through the Modly UI or via the /api/v1/settings endpoint according to the lightningpixel/modly source code.

What response formats does the Modly API support?

All endpoints return JSON responses for standard requests. For generation tasks, the API supports Server-Sent Events (SSE) streams when the stream parameter is set to true, allowing real-time progress updates as implemented in api/routers/generation.py.

Can external services monitor job progress in real-time?

Yes, services can either poll the specific job endpoint (such as /api/v1/generation/{job_id}) or consume the SSE stream opened during the initial POST request. The SSE approach provides lower latency updates for long-running 3D generation workflows.

Is the Modly API compatible with OpenAPI or Swagger documentation?

Because Modly uses FastAPI, it automatically generates an OpenAPI schema and interactive documentation. You can access the Swagger UI at /docs or the ReDoc interface at /redoc when the server is running, as defined in api/main.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}