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.

create_image_to_3d_session(image_url, *, generate_preview_mesh=False, auto_refine=False, preview_model='fast_sculpt', creativity='lowest', refine_speed='fast', polygon_count='high_poly', topology='tris', texture_resolution=2048, scaled_bbox=[], pivot_point=[0.0, 0.0, 0.0]) → dict[source]#

Creates an image-to-3D conversion session.

Parameters:

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

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_3d_preview(session_code, spin_url=None, scaled_bbox=[], pivot_point=[0.0, 0.0, 0.0]) → dict[source]#

Fetches a preview of the generated 3D model.

Parameters:

session_code (str) – The session code of the 3D model to preview.

Returns:

The response from the API with preview data.

Return type:

dict

get_3d_refine(session_code, scaled_bbox=[], pivot_point=[0.0, 0.0, 0.0]) → dict[source]#

Requests refinement for an existing 3D model.

Parameters:

session_code (str) – The session code of the 3D model to refine.

Returns:

The response from the API with refinement results.

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

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

property headers#

Constructs and returns the HTTP headers required for API requests.

class csm.CSMClient(api_key=None, base_url='https://api.csm.ai')[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.

image_to_3d(image, *, generate_spin_video=False, mesh_format='obj', output='./', timeout=200, verbose=True, scaled_bbox=[], pivot_point=[0.0, 0.0, 0.0], refine_speed='fast', preview_model='fast_sculpt') → 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 to be converted into a 3D mesh.

  • generate_spin_video (bool, optional) – If True, a spin video of the generated 3D mesh is created. Defaults to False.

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

  • 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. Defaults to 200 seconds.

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

  • scaled_bbox (list, optional) – A 3-element list specifying the scaled bounding box for the generated 3D model. Defaults to an empty list, meaning no custom bounding box.

  • pivot_point (list, optional) – A 3-element list specifying the pivot point for the 3D model’s orientation. Defaults to [0.0, 0.0, 0.0].

  • refine_speed (str, optional) – The refinement speed for the model generation process. Choices are ‘fast’ or ‘slow’. Defaults to ‘fast’.

  • preview_model (str, optional) – The preview model type to use during 3D mesh creation. Choices are ‘fast_sculpt’ or ‘turbo’. Defaults to ‘fast_sculpt’.

Returns:

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

Return type:

ImageTo3DResult

text_to_3d(prompt, *, style_id='', guidance=6, generate_spin_video=False, mesh_format='obj', output='./', timeout=200, verbose=True, scaled_bbox=[], pivot_point=[0.0, 0.0, 0.0], refine_speed='fast', preview_model='fast_sculpt') → 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.

  • generate_spin_video (bool, optional) – If True, a spin video of the generated 3D mesh is created. Defaults to False.

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

  • 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. Defaults to 200 seconds.

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

  • scaled_bbox (list, optional) – A 3-element list specifying the scaled bounding box for the generated 3D model. Defaults to an empty list, meaning no custom bounding box.

  • pivot_point (list, optional) – A 3-element list specifying the pivot point for the 3D model’s orientation. Defaults to [0.0, 0.0, 0.0].

  • refine_speed (str, optional) – The refinement speed for the model generation process. Choices are ‘fast’ or ‘slow’. Defaults to ‘fast’.

  • preview_model (str, optional) – The preview model type to use during 3D mesh creation. Choices are ‘fast_sculpt’ or ‘turbo’. Defaults to ‘fast_sculpt’.

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(session_code: str, mesh_path: str)[source]#

Output class for image-to-3d generation.

Parameters:

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

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

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

Output class for text-to-3d generation.

Parameters:

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

  • 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.

image_path: str#
mesh_path: str#
session_code: str#