ArchDiffusion v4.5-Ultra

ArchDiffusion v4.5 is our flagship rendering engine for architectural visualization, and the same engine that powers the mnml studio. It renders at 2K behind a deep reasoning ("thinking") step, and adds the two things v4.4 left to the model: an art direction for each discipline, and a lock that names the camera, the framing and the footprint rather than the geometry alone.

Every parameter v4.4 accepts, v4.5 accepts, with the same names and the same defaults — so an existing v4.4 request body renders on v4.5 unchanged. Only the output moves.

How it works: v4.5 composes your description and your expert-specific parameters into one ordered brief, then appends a per-discipline look block (the finish a leading archviz studio would publish) and closes with a per-discipline lock. Each expert type (exterior, interior, masterplan, landscape, product, plan, text-to-render) has its own specialized parameters, its own look and its own lock.

What's new in v4.5 (over v4.4):

  • A per-discipline look block. v4.4 composed no art direction, so the model supplied its own house style — which is how massing models ended up on display plinths. v4.5 states the finish for exteriors, interiors, plans, landscapes and 2D/3D masterplans separately. Applies to the photographic registers (photoreal, the default, and auto).
  • A lock that holds the camera. v4.4's closing clause named geometry, proportions, structure and openings, and never the camera — so the model was free to walk closer. v4.5's lock names the camera, the framing, the crop and the footprint too.
  • Drawings render on a drawing model. On Ultra, plan and masterplan are routed to a model measured as better at reading a drawing: sharper aerials, and no invented dimension strings or title blocks on a plan with annotations off. Same price.
  • Switched-off controls are spoken, not dropped. Setting greenery=none, water_features=none or landscape_lighting=none now emits an explicit exclusion. Silence let a photoreal render add the trees, the water and the path lights back.
  • Reference roles. reference_mode_1-4 says what each reference image is FOR — composition, style, material, atmosphere or color — and what to ignore in it, so two references stop competing for the same job.
  • Proposal mode. expert_name=text-to-render locks the SITE in your image and leaves the design free — the reverse of every other run.
  • Markup mode actually acts. v4.4 parsed markup_mode and did nothing with it on some paths; v4.5 honours it wherever it arrives.
  • The seed is forwarded to the engine. v4.4 accepted a seed and did not pass it on.
  • • Everything v4.4 already had: 2K output, the full expert parameter set, 8 render styles, precise/creative geometry, and manual camera control.

Credit Cost: 3 credits per generation — the same as v4.4, including the drawing route for plan and masterplan.

Migrating from v4.4? Change the URL and nothing else. Every parameter name, default and response field is unchanged. Two behavioural notes: has_collage is accepted but has no effect on v4.5 (stay on v4.4 if you rely on it), and the look block means a default render looks deliberately different — that is the upgrade, not a regression. v4.4 stays available and unchanged.

Endpoint

HTTP Method
POST https://api.mnmlai.dev/v1/archDiffusion-v45

Request

Send a POST request with multipart/form-data containing your source image and design parameters. The API processes images asynchronously through expert-specific AI pipelines, returning a request ID for status tracking.

How the v4.5 prompt is composed

v4.5 builds one ordered brief from your request. The order is deliberate: the rendering model weights the END of a prompt most and drops early constraints on long ones, so what must hold goes last.

  1. The task — edit the input image into a finished render.
  2. Your prompt, verbatim.
  3. The render style, as a written direction rather than a label.
  4. Reference-image roles, if you sent any.
  5. Your scene parameters, with switched-off controls stated as explicit exclusions.
  6. The look block — the finish for this discipline. It never outranks a setting you chose above it.
  7. The camera directive, when view_mode="manual".
  8. The lock — what must not change: geometry, proportions, openings, and now the camera, framing, crop and footprint.

Two shortcuts the composer takes on its own. A short, local instruction ("make the door black", "remove the tree") is sent as the instruction plus the lock, with the scene parameters dropped — wrapped in a full brief, four words lose to a stale sidebar. And expert_name="text-to-render" flips the lock onto the site instead of the building.

Want full control?

Set render_style to "raw" to pass your prompt straight through — no look block, no scene parameters, no lock. The one exception is markup_mode, which still rides along because it describes your input rather than the render. Sending "raw" with an empty prompt composes from your settings instead of failing.

Required Parameters

ParameterTypeDescription
imageRequiredFileSource architectural image (JPEG, PNG, WebP). Max 15MB, min 1KB
promptRecommendedStringDescription of desired transformation (max 2000 characters). Omitting it is not an error — the expert's own default stands in ("Modern building exterior", "Modern interior design", and so on) and the render is composed from your parameters. Over 2000 characters returns 400 PROMPT_TOO_LONG

Common Parameters (All Expert Types)

ParameterTypeDefaultDescription
expert_nameString"exterior"Expert mode: "exterior", "interior", "masterplan", "landscape", "plan", "product", "text-to-render". On v4.5, "text-to-render" treats your image as the SITE and leaves the design to your prompt
render_styleString"photoreal""raw", "photoreal", "cgi_render", "cad", "freehand_sketch", "clay_model", "illustration", "watercolor"
geometryString"precise""precise" (accurate geometry) or "creative" (artistic freedom)
view_modeString"auto""auto" (keep original camera) or "manual" (skip geometry block for full camera control)
seedNumberRandomSeed value (0-1000000). On v4.5 the seed IS forwarded to the rendering engine (v4.4 accepted it and dropped it), so repeating a request with the same seed and the same inputs gives a much closer result. Omit it and one is generated per request
annotationString"false"Enable annotations: "true" or "false"
show_dimensionsString"false"Show dimensions: "true" or "false"
markup_modeString"false"Enable markup mode: "true" or "false". When enabled, all annotations on the image are treated as mandatory edits
has_collageString"false"Accepted for compatibility with v4.4 but has no effect on v4.5 — the collage instruction is not part of the v4.5 brief. Use v4.4 if you need it
aspect_ratioString"auto"Output aspect ratio: "auto" (match the input image), "1:1", "16:9", "21:9", "3:2", "4:3", "5:4", "4:5", "3:4", "2:3", "9:16", plus the panoramic "4:1", "1:4", "8:1", "1:8". "match_input_image" is accepted as an alias for "auto". An unsupported value returns 400 INVALID_ASPECT_RATIO. The four panoramic ratios are not available for plan or masterplan on this tier — those render on the drawing model, which does not support them; the request is rejected with 400 rather than charged. They work on every other expert here, and on all experts on v4.5-Fast
output_formatString"png"Output image format: "png", "jpeg", "webp"
reference_image_1-4FileNoneOptional reference images (up to 4). The main image is always image 1; references follow in order
reference_mode_1-4String"auto"New in v4.5. What the matching reference_image_N is FOR: "composition", "style", "material", "atmosphere", "color", or "auto". Each role also states what to ignore in that image, so two references stop competing for the same job. An unrecognised value falls back to "auto"

Camera control needs two fields. A camera_angle is only honoured when view_mode is "manual" — with view_mode="auto" the engine keeps the input image's viewpoint and your angle is ignored. This matches v4.4. The product expert is the exception: its camera is always honoured.

Reference images anchor the output shape. When you send reference images with aspect_ratio="auto", v4.5 snaps the output to your input image's proportions rather than letting the ratio drift toward a reference. Set aspect_ratio explicitly to override.

Exterior Parameters

ParameterDefaultOptions
camera_angleautoauto, eye_level, elevation, low, elevated, aerial, top_down, close_up
camera_directionfrontfront, corner_right, right, back, left, corner_left
site_contextautoauto, urban, suburban, nature
greenerysomenone, some, lush
vehiclesfewnone, few, many
peoplefewnone, few, many
street_propsoffoff, on
motionsubtleoff, subtle, long_exposure
time_of_dayautoauto, day, morning, golden_hour, sunset, dusk, blue_hour, night
weatherclearclear, overcast, cloudy, hazy, rain, fog, snow
ground_wetnessdrydry, damp, wet

Note: Environmental parameters like time_of_day, weather, and ground_wetness are applied for photoreal and cgi_render styles. These parameters are ignored when using raw mode. When view_mode is set to "manual", the geometry block is skipped for full camera control.

Interior Parameters

Note: Interior expert now supports geometry mode (precise/creative) like exterior. When view_mode is set to "manual", the geometry block is skipped for full camera control.

ParameterDefaultOptions
room_typeautoliving room, bedroom, kitchen, bathroom, dining room, office, etc.
room_styleautoModern interior, Minimalism, Japandi, Industrial, Scandinavian, etc.
furnishing_levelautoauto, empty, minimal, moderate, full
indoor_plantsautoauto, none, some, lush
interior_accessoriesoffoff, on
lighting_modeautoauto, off, natural, artificial, mixed
floor_finishautoauto, matte, reflective
ambienceautoauto, daylight, golden_hour, night

Masterplan Parameters

ParameterDefaultOptions
plan_mode3d3d, 2d
urban_densityautoauto, low, medium, high
development_typeautoauto, residential, commercial, mixed_use, industrial, institutional, recreational
water_featuresautoauto, none, river, lake, coastal, fountains
greenerymoderatenone, sparse, moderate, lush

Landscape Parameters

ParameterDefaultOptions
landscape_stylemodernmodern, traditional, japanese, tropical, mediterranean, desert, etc.
vegetationmoderateminimal, moderate, lush, wild
water_featuresnonenone, pool, pond, fountain, stream, waterfall
hardscapepathwaysminimal, pathways, patio, deck, full
outdoor_furniturenonenone, minimal, moderate, full
landscape_lightingnonenone, subtle, accent, dramatic

Product Parameters

ParameterDefaultOptions
product_categoryfurniturefurniture, lighting, decor, kitchenware, electronics, fashion, jewelry, packaging, industrial, automotive
backgroundwhitewhite, gradient, studio, contextual, transparent
product_lightingsoftsoft, dramatic, natural, rim, flat
material_finishautoauto, matte, glossy, metallic, textured
shadow_stylecontactnone, contact, soft, dramatic, reflection

Plan Parameters

ParameterDefaultOptions
plan_view_mode2d2d, 3d
drawing_stylearchitecturaltechnical, architectural, sketch, diagram
color_modemonochromemonochrome, grayscale, colored
furniture_2doutlinenone, outline, detailed
wall_stylefilledoutlined, filled, poche
view_type_3disometrictop_down, bird_eye, isometric, section

Render Styles Guide

Available Render Styles

raw: No prompt enhancement - your exact prompt sent directly to the AI engine
photoreal: Photorealistic architectural photograph — real materials, natural light, accurate soft shadows. Carries the v4.5 look block.
cgi_render: High-end CGI archviz render — clean materials, crisp lighting, polished and premium
cad: Technical CAD line drawing — white background, crisp black linework with varied weights, completely flat. Also drops the scene-dressing parameters (people, weather, time of day, …) so they cannot dilute the drawing
freehand_sketch: Loose hand-drawn concept sketch — marker and fineliner, deliberately imperfect: wobbly lines, overshoots, visible construction lines
clay_model: Matte clay render showing pure form and volume. Passed to the engine as a plain style label rather than a written direction
illustration: Flat illustration art style. Passed as a plain style label rather than a written direction
watercolor: Loose architect watercolor — ink linework over uneven washes, blooms and backruns, visible paper grain

The look block only applies to the photographic registers. It is composed for photoreal (the default) and auto only — a CAD drawing, a sketch or a watercolor has no photographic finish to describe, so asking for one would fight the style you chose. If you want the v4.5 art direction, leave render_style at its default. The camera lock, the exclusion vocabulary and the reference roles apply to every style.

Response

The API processes your request asynchronously and immediately returns a response containing a unique request ID. Use this ID with the Status Check endpoint to monitor processing progress and retrieve the final generated image.

parameters.drawingRoute is true when a plan or masterplan was sent to the drawing model — in which case thinkingLevel reads "n/a (drawing route)", because that model takes no thinking budget. Both fields are informational; nothing else about the request or the polling flow changes.

Success Response (200 OK)

{
  "status": "success",
  "id": "vysqf2nr0drmc0ctqx5tkdse48",
  "prompt": "Modern commercial building with glass facade",
  "expert_name": "exterior",
  "parameters": {
    "renderStyle": "photoreal",
    "geometry": "precise",
    "viewMode": "auto",
    "annotation": false,
    "showDimensions": false,
    "referenceImageCount": 0,
    "aspectRatio": "auto",
    "resolution": "2K",
    "thinkingLevel": "high",
    "drawingRoute": false
  },
  "credits": 97
}

Code Examples

1. Basic Exterior Rendering

curl -X POST https://api.mnmlai.dev/v1/archDiffusion-v45 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@/path/to/building.jpg" \
  -F "prompt=Modern commercial building with glass facade" \
  -F "expert_name=exterior" \
  -F "render_style=photoreal"

2. Interior with Full Parameters

curl -X POST https://api.mnmlai.dev/v1/archDiffusion-v45 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@/path/to/room.jpg" \
  -F "prompt=Luxury penthouse living room" \
  -F "expert_name=interior" \
  -F "render_style=photoreal" \
  -F "room_type=living room" \
  -F "room_style=Modern interior" \
  -F "furnishing_level=full" \
  -F "indoor_plants=some" \
  -F "lighting_mode=natural" \
  -F "ambience=golden_hour" \
  -F "aspect_ratio=16:9"

3. Product Rendering

curl -X POST https://api.mnmlai.dev/v1/archDiffusion-v45 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@/path/to/chair-sketch.jpg" \
  -F "prompt=Designer lounge chair with walnut frame" \
  -F "expert_name=product" \
  -F "render_style=photoreal" \
  -F "product_category=furniture" \
  -F "background=studio" \
  -F "product_lighting=soft" \
  -F "material_finish=wood" \
  -F "shadow_style=soft"

4. Masterplan on the drawing route

# On v4.5-Ultra, plan and masterplan render on the drawing model.
# Nothing in the request selects it — it is chosen from expert_name.
curl -X POST https://api.mnmlai.dev/v1/archDiffusion-v45 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@/path/to/site-plan.png" \
  -F "prompt=Present this masterplan as a finished aerial" \
  -F "expert_name=masterplan" \
  -F "plan_mode=3d" \
  -F "greenery=moderate" \
  -F "urban_density=medium"

5. Reference images with explicit roles

# Each reference is told what it is for, and what to ignore in it.
curl -X POST https://api.mnmlai.dev/v1/archDiffusion-v45 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@/path/to/massing.jpg" \
  -F "prompt=Timber and glass pavilion" \
  -F "expert_name=exterior" \
  -F "reference_image_1=@/path/to/timber-cladding.jpg" \
  -F "reference_mode_1=material" \
  -F "reference_image_2=@/path/to/dusk-lighting.jpg" \
  -F "reference_mode_2=atmosphere"

6. Proposal on a site photo (text-to-render)

# The SITE in your image is locked; the building is yours to describe.
curl -X POST https://api.mnmlai.dev/v1/archDiffusion-v45 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@/path/to/empty-site.jpg" \
  -F "prompt=A six-storey brick apartment block on this site" \
  -F "expert_name=text-to-render"

7. Node.js Implementation

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('image', fs.createReadStream('building.jpg'));
form.append('prompt', 'Modern residential building');
form.append('expert_name', 'exterior');
form.append('render_style', 'photoreal');
form.append('geometry', 'precise');
form.append('time_of_day', 'golden_hour');
form.append('greenery', 'lush');
form.append('weather', 'clear');

const response = await axios.post(
  'https://api.mnmlai.dev/v1/archDiffusion-v45',
  form,
  {
    headers: {
      'Accept': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY',
      ...form.getHeaders()
    }
  }
);

console.log('Request ID:', response.data.id);
console.log('Remaining credits:', response.data.credits);

8. Python Implementation

import requests

url = 'https://api.mnmlai.dev/v1/archDiffusion-v45'

files = {
    'image': open('building.jpg', 'rb')
}

data = {
    'prompt': 'Modern commercial building with glass facade',
    'expert_name': 'exterior',
    'render_style': 'photoreal',
    'geometry': 'precise',
    'camera_angle': 'eye_level',
    'time_of_day': 'golden_hour',
    'greenery': 'some',
    'vehicles': 'few',
    'people': 'few'
}

headers = {
    'Accept': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()

print(f"Request ID: {result['id']}")
print(f"Remaining credits: {result['credits']}")

Checking Processing Status

Status Check Endpoint
GET https://api.mnmlai.dev/v1/status/{id}

Processing Time: Typically 30-60 seconds. Poll the status endpoint every 3-5 seconds until the status becomes "succeeded" or "failed".

Best Practices

Image Guidelines

  • Use high-quality source images (1024px or larger recommended)
  • Supported formats: JPEG, PNG, WebP
  • File size: 1KB - 15MB per image
  • Images are automatically resized to 1344px width

Geometry Mode Selection

  • precise: Maximum architectural accuracy, preserves exact geometry - best for technical visualizations
  • creative: More artistic freedom, enhanced details - best for conceptual presentations

Expert-Specific Tips

  • Exterior: Use time_of_day and weather for dramatic atmospheric effects
  • Interior: Match room_style with furnishing_level for cohesive results
  • Product: Use studio background with soft lighting for clean product shots
  • Masterplan: Use 3d plan_mode with aerial camera for urban visualizations

Error Handling

Common Error Responses

// 400 Bad Request - Missing image
{
  "status": "error",
  "code": "MISSING_IMAGE",
  "message": "Image file is required"
}

// 400 Bad Request - Insufficient credits
{
  "status": "error",
  "code": "NO_CREDITS",
  "message": "You do not have enough credits to use this feature. This API requires 3 credits.",
  "details": { "credits": 2, "required": 3 }
}

// 400 Bad Request - Image too large
{
  "status": "error",
  "code": "IMAGE_TOO_LARGE",
  "message": "Image file is too large",
  "details": { "size": 20000000, "maxSize": 15728640 }
}

// 400 Bad Request - Unsupported aspect ratio
{
  "status": "error",
  "code": "INVALID_ASPECT_RATIO",
  "message": "Unsupported aspect_ratio value. Allowed values: match_input_image, auto, 1:1, ...",
  "details": {
    "receivedAspectRatio": "7:3",
    "allowedAspectRatios": ["match_input_image", "auto", "1:1", "..."],
    "drawingRoute": false
  }
}

// 400 Bad Request - A panoramic ratio on the drawing route.
// plan and masterplan render on the drawing model on this tier; it does
// not support 4:1, 1:4, 8:1 or 1:8. Refused here rather than charged.
{
  "status": "error",
  "code": "INVALID_ASPECT_RATIO",
  "message": "The "masterplan" expert renders on the drawing model on this tier, which does not support panoramic aspect ratios. ...",
  "details": {
    "receivedAspectRatio": "8:1",
    "allowedAspectRatios": ["match_input_image", "auto", "1:1", "..."],
    "drawingRoute": true
  }
}

// 400 Bad Request - Body was not multipart/form-data
{
  "status": "error",
  "code": "INVALID_REQUEST_BODY",
  "message": "Request body must be multipart/form-data. ...",
  "details": { "receivedContentType": "application/json" }
}

Credits are only spent on accepted requests. Every validation error above is returned before the engine is called, so a rejected request costs nothing. If a request is accepted and the render then fails — or completes without producing an image — the credits are refunded automatically, once, against that request ID.

Occasionally a render is rejected by the content checker. The rendering engine screens every request, and the screen is probabilistic — the same benign architectural prompt can pass on one attempt and be flagged on the next. When it happens the request is accepted, so you get a request ID, and the render then produces nothing; the credits are refunded automatically and the status endpoint reports the failure. Retry the request.