Design API

Design API

The Design API enables creation and management of 3D room designs, AR sessions, collaborative editing, and integration with the product catalog for immersive home improvement planning.

Base URL: https://api.osus.ai/v1/design

3D Design Features

Real-time 3D scene editing
AR/VR compatibility
Collaborative editing
Direct product integration

Supported Room Types

Living Room Bedroom Kitchen Bathroom Office

Create Design Project

Create a new 3D room design project with specified dimensions and style.

POST /design/projects

Request Body

Parameter Type Required Description
name string Yes Project name
roomType string Yes living_room, bedroom, kitchen, bathroom, office
style string Yes modern, classic, minimalist, egyptian, industrial
dimensions object Yes Room dimensions in meters
templateId string No Base template UUID (optional)
description string No Project description
isPublic boolean No Make project publicly viewable

Dimensions Object

Field Type Description Range
length number Room length in meters 2.0 - 20.0
width number Room width in meters 2.0 - 20.0
height number Room height in meters 2.4 - 5.0

Example Request

curl -X POST https://api.osus.ai/v1/design/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Modern Living Room",
    "description": "A contemporary living space with Egyptian touches",
    "roomType": "living_room",
    "style": "modern",
    "dimensions": {
      "length": 5.0,
      "width": 4.0,
      "height": 3.0
    },
    "templateId": "tmpl-modern-living-001",
    "isPublic": false
  }'

Response

{
  "success": true,
  "data": {
    "project": {
      "id": "proj-123456",
      "name": "My Modern Living Room",
      "description": "A contemporary living space with Egyptian touches",
      "roomType": "living_room",
      "style": "modern",
      "dimensions": {
        "length": 5.0,
        "width": 4.0,
        "height": 3.0,
        "area": 20.0
      },
      "items": [],
      "sceneData": {
        "version": "1.0",
        "camera": {
          "position": { "x": 2.5, "y": 1.8, "z": 2.0 },
          "target": { "x": 2.5, "y": 0, "z": 2.0 },
          "fov": 75
        },
        "lighting": {
          "ambientLight": {
            "color": "#ffffff",
            "intensity": 0.4
          },
          "directionalLights": [
            {
              "position": { "x": 10, "y": 10, "z": 5 },
              "color": "#ffffff",
              "intensity": 1.0
            }
          ]
        },
        "walls": [
          {
            "id": "wall-1",
            "points": [
              { "x": 0, "y": 0 },
              { "x": 5, "y": 0 }
            ],
            "height": 3.0,
            "material": "paint",
            "color": "#f5f5f5"
          }
        ],
        "floor": {
          "material": "ceramic",
          "color": "#e8e8e8",
          "texture": "tiles"
        },
        "objects": []
      },
      "thumbnailUrl": null,
      "isPublic": false,
      "shareToken": null,
      "totalCost": 0,
      "status": "draft",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z",
      "lastAccessedAt": "2025-01-15T10:30:00Z"
    },
    "sceneData": {
      "version": "1.0",
      "camera": {...},
      "lighting": {...},
      "walls": [...],
      "floor": {...},
      "objects": []
    }
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "requestId": "req_123456"
}

Get Design Project

Retrieve a specific design project with its complete scene data.

GET /design/projects/{projectId}

Path Parameters

Parameter Type Description
projectId string Project UUID

Query Parameters

Parameter Type Description
include string Include related data: scene,items,collaborators
version string Specific version number (optional)

Example Request

curl -X GET 'https://api.osus.ai/v1/design/projects/proj-123456?include=scene,items' \
  -H "Authorization: Bearer YOUR_API_KEY"

Project Items Management

Add, update, and remove 3D objects (products) in design projects.

POST /design/projects/{projectId}/items

Add product to project

PUT /design/projects/{projectId}/items/{itemId}

Update item position/properties

DELETE /design/projects/{projectId}/items/{itemId}

Remove item from project

Add Item Request

Parameter Type Description
productId string Product UUID
variantId string Product variant UUID (optional)
position object 3D position {x, y, z} in meters
rotation object 3D rotation {x, y, z} in radians
scale object 3D scale {x, y, z} multiplier
quantity integer Number of items (default: 1)
customization object Product customization options

Example Add Item Request

curl -X POST https://api.osus.ai/v1/design/projects/proj-123456/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "variantId": "var-001",
    "position": {
      "x": 2.5,
      "y": 0.0,
      "z": 1.0
    },
    "rotation": {
      "x": 0,
      "y": 1.57,
      "z": 0
    },
    "scale": {
      "x": 1.0,
      "y": 1.0,
      "z": 1.0
    },
    "quantity": 1,
    "customization": {
      "color": "blue",
      "material": "leather"
    }
  }'

Item Response

{
  "success": true,
  "data": {
    "item": {
      "id": "item-001",
      "projectId": "proj-123456",
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "product": {
        "name": "Modern 3-Seat Sofa",
        "image": "https://cdn.osus.ai/products/sofa-001-main.jpg",
        "price": 2500,
        "threeDModel": {
          "url": "https://cdn.osus.ai/3d/sofa-001.glb",
          "format": "glb"
        }
      },
      "variantId": "var-001",
      "variant": {
        "name": "Blue Leather",
        "color": "Blue"
      },
      "position": {
        "x": 2.5,
        "y": 0.0,
        "z": 1.0
      },
      "rotation": {
        "x": 0,
        "y": 1.57,
        "z": 0
      },
      "scale": {
        "x": 1.0,
        "y": 1.0,
        "z": 1.0
      },
      "quantity": 1,
      "unitPrice": 2500,
      "totalPrice": 2500,
      "customization": {
        "color": "blue",
        "material": "leather"
      },
      "inCart": false,
      "createdAt": "2025-01-15T11:00:00Z",
      "updatedAt": "2025-01-15T11:00:00Z"
    }
  }
}

3D Rendering

Generate high-quality renders and images of design projects.

POST /design/projects/{projectId}/render

Render Request

Parameter Type Description
quality string Render quality: low, medium, high, ultra
resolution object Image resolution {width, height}
camera object Camera position and angle
lighting string Lighting preset: natural, studio, dramatic
format string Output format: jpg, png, webp

Example Render Request

curl -X POST https://api.osus.ai/v1/design/projects/proj-123456/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quality": "high",
    "resolution": {
      "width": 1920,
      "height": 1080
    },
    "camera": {
      "position": { "x": 2.5, "y": 1.8, "z": 4.0 },
      "target": { "x": 2.5, "y": 1.0, "z": 1.0 },
      "fov": 75
    },
    "lighting": "natural",
    "format": "jpg"
  }'

Render Response

{
  "success": true,
  "data": {
    "render": {
      "id": "render-001",
      "projectId": "proj-123456",
      "status": "completed",
      "imageUrl": "https://cdn.osus.ai/renders/render-001-high.jpg",
      "quality": "high",
      "resolution": {
        "width": 1920,
        "height": 1080
      },
      "renderTime": 45.2,
      "fileSize": 2457600,
      "format": "jpg",
      "createdAt": "2025-01-15T11:15:00Z",
      "expiresAt": "2025-01-22T11:15:00Z"
    }
  }
}

AR Sessions

Create and manage augmented reality viewing sessions for projects.

POST /design/projects/{projectId}/ar-session

AR Session Request

Parameter Type Description
platform string AR platform: ios, android, web
tracking object Tracking configuration
maxDuration integer Max session duration in minutes

Example AR Session Request

curl -X POST https://api.osus.ai/v1/design/projects/proj-123456/ar-session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "ios",
    "tracking": {
      "type": "plane",
      "planeDetection": ["horizontal"],
      "lightEstimation": true,
      "occlusionEnabled": false
    },
    "maxDuration": 30
  }'

AR Session Response

{
  "success": true,
  "data": {
    "session": {
      "id": "ar-session-001",
      "projectId": "proj-123456",
      "platform": "ios",
      "status": "active",
      "sessionToken": "ar_tok_xyz123",
      "arAssets": {
        "sceneUrl": "https://cdn.osus.ai/ar/scenes/proj-123456.usdz",
        "objects": [
          {
            "itemId": "item-001",
            "assetUrl": "https://cdn.osus.ai/ar/objects/sofa-001.usdz",
            "position": { "x": 0, "y": 0, "z": 0 },
            "scale": 1.0
          }
        ]
      },
      "tracking": {
        "type": "plane",
        "planeDetection": ["horizontal"],
        "lightEstimation": true,
        "occlusionEnabled": false
      },
      "maxDuration": 30,
      "expiresAt": "2025-01-15T11:45:00Z",
      "createdAt": "2025-01-15T11:15:00Z"
    }
  }
}

Collaboration

Share projects and enable real-time collaborative editing.

POST /design/projects/{projectId}/share

Share project with others

GET /design/projects/{projectId}/collaborators

Get project collaborators

PUT /design/projects/{projectId}/collaborators/{userId}

Update collaborator permissions

Share Project Request

curl -X POST https://api.osus.ai/v1/design/projects/proj-123456/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collaborators": [
      {
        "email": "designer@example.com",
        "permission": "edit"
      },
      {
        "email": "client@example.com",
        "permission": "view"
      }
    ],
    "isPublic": false,
    "allowComments": true,
    "expiresAt": "2025-02-15T00:00:00Z"
  }'

Scene Data Structure

Understanding the 3D scene data format used by the Design API.

Scene Data Schema

{
  "version": "1.0",
  "metadata": {
    "created": "2025-01-15T10:30:00Z",
    "author": "user-001",
    "software": "OSUS Design API v1.0"
  },
  "room": {
    "type": "living_room",
    "dimensions": {
      "length": 5.0,
      "width": 4.0,
      "height": 3.0
    },
    "walls": [
      {
        "id": "wall-1",
        "points": [
          { "x": 0, "y": 0 },
          { "x": 5, "y": 0 }
        ],
        "height": 3.0,
        "thickness": 0.2,
        "material": "drywall",
        "color": "#ffffff",
        "texture": null
      }
    ],
    "floor": {
      "material": "ceramic",
      "color": "#f0f0f0",
      "texture": "tiles",
      "pattern": "square"
    },
    "ceiling": {
      "material": "paint",
      "color": "#ffffff",
      "height": 3.0
    }
  },
  "objects": [
    {
      "id": "obj-001",
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "furniture",
      "name": "Modern Sofa",
      "transform": {
        "position": { "x": 2.5, "y": 0.0, "z": 1.0 },
        "rotation": { "x": 0, "y": 1.57, "z": 0 },
        "scale": { "x": 1.0, "y": 1.0, "z": 1.0 }
      },
      "materials": [
        {
          "id": "mat-fabric",
          "type": "fabric",
          "color": "#4169e1",
          "roughness": 0.8,
          "metallic": 0.0
        }
      ]
    }
  ],
  "lighting": {
    "ambientLight": {
      "color": "#ffffff",
      "intensity": 0.4
    },
    "directionalLights": [
      {
        "position": { "x": 10, "y": 10, "z": 5 },
        "target": { "x": 0, "y": 0, "z": 0 },
        "color": "#ffffff",
        "intensity": 1.0,
        "castShadows": true
      }
    ]
  },
  "camera": {
    "position": { "x": 2.5, "y": 1.8, "z": 4.0 },
    "target": { "x": 2.5, "y": 1.0, "z": 1.0 },
    "fov": 75,
    "near": 0.1,
    "far": 100.0
  }
}

Error Codes

HTTP Status Error Code Description
400 INVALID_DIMENSIONS Room dimensions are out of allowed range
400 INVALID_POSITION Object position is outside room boundaries
400 PRODUCT_NOT_3D_COMPATIBLE Product doesn't have 3D model available
403 PROJECT_ACCESS_DENIED Insufficient permissions to access project
404 PROJECT_NOT_FOUND Design project not found
404 TEMPLATE_NOT_FOUND Design template not found
409 PROJECT_NAME_EXISTS Project name already exists for user
422 RENDER_FAILED 3D rendering process failed
429 RENDER_QUOTA_EXCEEDED Rendering quota exceeded for current plan