API Reference#

class csm.BackendClient(api_key=None, base_url='https://api.csm.ai')[source]#

A backend client class for raw GET/POST requests to the REST API.

Warning

This class should not be accessed directly. Instead, use CSMClient to interface with the API.

Parameters:

  • api_key (str, optional) – API key for the CSM account you would like to use. If not provided, the environment variable CSM_API_KEY is used instead.

  • base_url (str) – Base url for the API. In general this should not be modified; it is included only for debugging purposes.

property headers#

Constructs and returns the HTTP headers required for API requests.

create_image_to_3d_session(image_url, **kwargs) → dict[source]#

Creates an image-to-3D conversion session.

Parameters:

  • image_url (str) – URL of the image to convert into a 3D model.

  • **kwargs (dict, optional) – Additional parameters for customizing the image-to-3D process. For a complete list of supported options, see the REST API documentation: Session Parameters.

Returns:

The response from the API containing session details.

Return type:

dict

get_image_to_3d_session_info(session_code) → dict[source]#

Fetches information about an existing image-to-3D session.

Parameters:

session_code (str) – The session code of the image-to-3D session.

Returns:

The response from the API containing session details.

Return type:

dict

create_text_to_image_session(prompt, style_id='', guidance=6) → dict[source]#

Creates a text-to-image session.

Parameters:

prompt (str) – The text prompt for generating an image.

Returns:

The response from the API with session details.

Return type:

dict

get_text_to_image_session_info(session_code: str) → dict[source]#

Fetches information for an existing text-to-image session.

Parameters:

session_code (str) – The session code of the text-to-image session.

Returns:

The response from the API with session details.

Return type:

dict

class csm.CSMClient(api_key=None, base_url='https://api.csm.ai', verbose=True)[source]#

Core client utility for accessing the CSM API.

Parameters:

  • api_key (str, optional) – API key for the CSM account you would like to use. If not provided, the environment variable CSM_API_KEY is used instead.

  • base_url (str) – Base url for the API. In general this should not be modified; it is included only for debugging purposes.

  • verbose (bool) – If True, the client outputs detailed progress information. Verbosity can also be specified per-session with method argument verbose. Defaults to True.

start_image_to_3d(image, *, verbose=None, **kwargs) → str[source]#

Start an image-to-3d session and return the session code.

Parameters:

  • image (str or PIL.Image.Image) – The input image. May be provided as a URL, a local file path, or a PIL.Image.Image instance.

  • verbose (bool, optional) – If True, outputs detailed progress information. Defaults to self.verbose.

  • **kwargs (dict, optional) –

    Additional parameters for customizing the image-to-3D process. For a complete list of supported options, see the REST API documentation: Session Parameters.

Returns:

The image-to-3d session code.

Return type:

str

poll_image_to_3d(session_code, *, mesh_format='glb', output='./', timeout=1000, poll_interval=5, verbose=None) → ImageTo3DResult[source]#

Poll an image-to-3d session and return the result when it arrives.

Parameters:

  • session_code (str) – The image-to-3d session code.

  • mesh_format (str, optional) – The format of the output 3D mesh file. Choices are [‘obj’, ‘glb’, ‘fbx’, ‘usdz’]. Defaults to ‘glb’.

  • output (str, optional) – The directory path where output files will be saved.

  • timeout (int, optional) – The maximum time (in seconds) to wait for the 3D mesh generation.

  • poll_interval (int) – Time to wait (in seconds) between iterations while polling for a result.

  • verbose (bool, optional) – If True, outputs detailed progress information. Defaults to self.verbose.

Returns:

Result object containing the local path of the generated mesh file and session code.

Return type:

ImageTo3DResult

image_to_3d(image, *, mesh_format='glb', output='./', timeout=1000, poll_interval=5, verbose=None, **kwargs) → ImageTo3DResult[source]#

Generate a 3D mesh from an image.

The input image can be provided as a URL, a local path, or a PIL.Image.Image.

Parameters:

  • image (str or PIL.Image.Image) – The input image. May be provided as a URL, a local file path, or a PIL.Image.Image instance.

  • mesh_format (str, optional) – The format of the output 3D mesh file. Choices are [‘obj’, ‘glb’, ‘fbx’, ‘usdz’]. Defaults to ‘glb’.

  • output (str, optional) – The directory path where output files will be saved.

  • timeout (int, optional) – The maximum time (in seconds) to wait for the 3D mesh generation.

  • poll_interval (int) – Time to wait (in seconds) between iterations while polling for a result.

  • verbose (bool, optional) – If True, outputs detailed progress information. Defaults to self.verbose.

  • **kwargs (dict, optional) –

    Additional parameters for customizing the image-to-3D process. For a complete list of supported options, see the REST API documentation: Session Parameters.

Returns:

Result object containing the local path of the generated mesh file and session code.

Return type:

ImageTo3DResult

start_text_to_image(prompt, *, style_id='', guidance=6, verbose=None) → str[source]#

Start a text-to-image session and return the session code.

Parameters:

  • prompt (str) – The input text prompt to generate an image based on text description.

  • style_id (str, optional) – The style ID that influences the visual characteristics of the generated model. Defaults to an empty string, meaning no specific style is applied.

  • guidance (int, optional) – A parameter that adjusts guidance strength, affecting how closely the generation follows the input text. Default is 6.

  • verbose (bool, optional) – If True, outputs detailed progress information. Defaults to self.verbose.

Returns:

The text-to-image session code.

Return type:

str

poll_text_to_image(session_code, *, output='./', timeout=1000, poll_interval=5, verbose=None) → TextToImageResult[source]#

Poll a text-to-image session and return the result when it arrives.

Parameters:

  • session_code (str) – The text-to-image session code.

  • output (str, optional) – The directory path where output files will be saved. Defaults to the current directory.

  • timeout (int, optional) – The maximum time (in seconds) to wait for the 3D mesh generation.

  • poll_interval (int) – Time to wait (in seconds) between iterations while polling for a result.

  • verbose (bool, optional) – If True, outputs detailed progress information. Defaults to self.verbose.

Returns:

Result object containing the local path of the generated image and session code.

Return type:

TextToImageResult

text_to_3d(prompt, *, style_id='', guidance=6, mesh_format='glb', output='./', timeout=1000, poll_interval=5, verbose=None, **kwargs) → TextTo3DResult[source]#

Generate a 3D mesh from a text prompt.

Parameters:

  • prompt (str) – The input text prompt to generate a 3D model based on text description.

  • style_id (str, optional) – The style ID that influences the visual characteristics of the generated model. Defaults to an empty string, meaning no specific style is applied.

  • guidance (int, optional) – A parameter that adjusts guidance strength, affecting how closely the generation follows the input text. Default is 6.

  • mesh_format (str, optional) – The format of the output 3D mesh file. Choices are [‘obj’, ‘glb’, ‘fbx’, ‘usdz’]. Defaults to ‘glb’.

  • output (str, optional) – The directory path where output files (mesh and video, if generated) will be saved. Defaults to the current directory.

  • timeout (int, optional) – The maximum time (in seconds) to wait for the 3D mesh generation.

  • poll_interval (int) – Time to wait (in seconds) between iterations while polling for a result.

  • verbose (bool, optional) – If True, outputs detailed progress information. Defaults to self.verbose.

  • **kwargs (dict, optional) –

    Additional parameters for customizing the image-to-3D process. For a complete list of supported options, see the REST API documentation: Session Parameters.

Returns:

Result object. Contains the local path of the generated mesh file, as well as the image generated as part of the pipeline, and session code.

Return type:

TextTo3DResult

class csm.ImageTo3DResult(mesh_path: str, session_code: str, session_data: dict)[source]#

Output class for image-to-3d generation.

Parameters:

  • mesh_path (str) – Local path of the generated mesh file.

  • session_code (str) – The image-to-3d session code.

  • session_data (dict) – Full image-to-3d session data returned by the REST API

mesh_path: str#
session_code: str#
session_data: dict#
class csm.TextTo3DResult(mesh_path: str, image_path: str, session_code: str, session_data: dict)[source]#

Output class for text-to-3d generation.

Parameters:

  • mesh_path (str) – Local path of the generated mesh file.

  • image_path (str) – Local path of the image generated as part of text-to-3d.

  • session_code (str) – The image-to-3d session code.

  • session_data (dict) – Full image-to-3d session data returned by the REST API

mesh_path: str#
image_path: str#
session_code: str#
session_data: dict#
class csm.TextToImageResult(image_path: str, session_code: str, session_data: dict)[source]#

Output class for text-to-3d generation.

Parameters:

  • image_path (str) – Local path of the generated image.

  • session_code (str) – The text-to-image session code.

  • session_data (dict) – Full text-to-image session data returned by the REST API

image_path: str#
session_code: str#
session_data: dict#