Quick Start

In this example, we'll be generating a 3D asset from an image using our Image to 3D sculpt model.

We'll be using the REST API, but if you'd prefer to use our Python package, docs can be found here (opens in a new tab).

First, create an API key from your user profile on the Cube Webapp (opens in a new tab).

Creating an Image to 3D session

We'll start by creating an Image to 3D session.

const response = await fetch('https://api.csm.ai/image-to-3d-sessions', {
  method: 'POST',
  headers: {
    'x-api-key': '<X-API_KEY>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ image_url: '<IMAGE-URL>', texture_model: "none" })
});
 
const session = await response.json();

The response will look something like this:

{
    "error": "",
    "message": "Created",
    "statusCode": 201,
    "data": {
        "session_code": "SESSION_1733505717_7021136",
        "progress": { "sculpt": { "status": "queued", ... } }
        ... // other fields
    }
}

Because Image to 3D inference can take a variable amount of time based on the settings, generation happens asynchronously. This means that we'll need to poll the session until it's complete.

Getting your session

To poll the session, we'll use the session_code from the response above.

let session = null;
while (session === null || session.data.progress.sculpt.status !== 'done') {
    const response = await fetch(`https://api.csm.ai/image-to-3d-sessions/${session_code}`);
    session = await response.json();
    // wait a few seconds before polling again
    await new Promise(resolve => setTimeout(resolve, 5000));
}
 
const meshUrl = session.data.mesh_url_glb;

Now we have a URL to download a GLB file containing the 3D mesh. Other formats and metadata can be found in the session.data object, described in more detail in the get Image-to-3D session docs.

fetch(meshUrl)
  .then(function(response) {
    if (!response.ok) {
      throw new Error('Unexpected response ' + response.statusText);
    }
 
    const fileStream = fs.createWriteStream('file.glb');
    response.body.pipe(fileStream);
 
    fileStream.on('finish', function() {
      console.log('Download complete.');
    });
 
    fileStream.on('error', function(err) {
      console.error('Error writing file:', err);
    });
  })
  .catch(function(err) {
    console.error('Error downloading file:', err);
  });

Introduction Quick Primer