Sessions Overview

Sessions are the core objects in Cube and the CSM API. They represent asynchronous operations that generate outputs such as images or 3D meshes.

Understanding the Workflow

A typical workflow with the CSM API follows these steps:

1. Create a session using POST /v3/sessions/
2. Wait for completion: monitor the session until it finishes, using one of these methods:
   • Poll the session status via GET /v3/sessions/{session_code}
   • Receive webhook notifications when session status changes (recommended)
   • Connect through a websocket to get real-time status updates (docs coming soon)
3. Retrieve results: once complete, get the session output using GET /v3/sessions/{session_code}

Key Session Properties

Understanding these essential properties will help you work effectively with sessions:

Type

The session type defines what kind of operation the session performs and the input/output API schemas.

Different types of sessions:

• image_to_3d - Generate 3D models from a single image
• multiview_to_3d - Generate 3D models from multiple images
• text_to_image - Generate images from text
• image_to_kit - Generate a kit of 3D parts from a single image
• retopology - Use AI to retopologize 3D meshes

Session ID

Each session has a unique identifier called _id, which you’ll use to reference the session in API calls.

Status

The session status indicates the current state of the session:

• incomplete - Session is created but still processing; output not yet ready
• complete - Session has successfully finished processing
• failed - Session encountered an error and could not complete