Tutorials →

Python Beginner Tutorial

Welcome to Zoo. We are building tools to be the backbone infrastructure for hardware tools.

Welcome to our Python beginner tutorial. This is primarily for those that have little coding experience, have no idea what an API is, or have no idea how to use them.

What is an API?

API stands for Application Programming Interface. The key to an API is that it allows applications to talk and be used by one another. Here are some current examples of API's used today.

Uber drivers use Google Maps for navigation in the Uber app.
Duolingo allows users to log in using their Facebook information.
Shopify uses Stripe to process credit card payments.

API's are powerful. Let's take the Uber example above. It would take a lot of time and engineers to develop a map feature similar to Google Maps within the Uber app. Uber uses Google Maps' API to access it within their own app. Of course, Uber pays a portion of their sales to Google in return for using their API.

Let's Get Started

For you to communicate with Zoo's website, you must have an API key. When you make an API command, you will pass this API key along with your command, so that we can verify it's you.

You will see your API token below if you are signed in and have already generated one. If all you see is "Generate your first API token," then you currently do not have a token. Follow the steps below to generate an API key:

Create an account. If you haven't already, you can create an account here
Sign in. Once you've signed up for an account, make sure you are signed in.
Generate an API key. You can either go into your account settings to generate an API key, or you can press the button below and we will take care of it for you!

🚨🚨🚨 Please take a moment to sign up. 🚨🚨🚨

It's required in order to generate an API key and follow this tutorial.

Executing From Your Computer

Once you have executed an API command from the litterbox, it is time for you to execute a command directly from your computer.

First, we want to make sure you have the right tools to make your first API command from your computer. We will provide you with almost everything you need. There are a few files that you will need to download from the KittyCAD repository:

Download Here

The link will have you download a zip file. Place this zip file in an easy-to-access location on your computer (the Desktop is a simple spot). The .zip file contains many files, but there are two files that we will be working with: a 3D model (dodecahedron.obj) and a python script (convert.py).

Jump to the appropriate tutorial for your setup

Mac
Windows
Linux

Mac

Once you download the .zip file and place it somewhere you can easily access, extract the contents of your zip file. You can do this by double-clicking on the file. This will unpack the zip file and place a new folder called litterbox-main with all the contents into your directory.
Install the latest version of Python for your machine here: Install Python
- make sure you download the correct version for Mac
Once you download Python, you will need to open your Terminal. You can open Terminal in a few ways:
- Press "cmd" + "space" and type in "Terminal" and hit "return"
- Press the magnifying glass icon on the top-right of your screen, type "Terminal" in the search box, and hit "return".
- Go to your Applications/Utilities folder. Double-click Terminal
Once the Terminal is open, you will need to navigate to the folder you downloaded. As an example, let's say you put them on the Desktop. You would type the following in your Terminal and hit "return":

cd ~/Desktop/litterbox-main

cd stands for change directory. Once you hit "return", you will be working inside the Desktop. For another example, let's say you put your files in a folder called ZooPractice within the Documents folder. This would look like so:

cd ~/Documents/ZooPractice/litterbox-main

You will now be working inside the litterbox-main folder you placed inside the ZooPractice folder.

Another method for changing directories is if you see the folder you want to move into (whether through Finder or the Desktop), you can type "cd" and then just drag and drop the folder onto Terminal, it will automatically fill out the file path for you. Just hit "return".

Once inside the correct folder, input the following command into Terminal. Simply copy and paste the following

export KITTYCAD_API_TOKEN="YOUR-API-TOKEN"
pip3 install virtualenv
python3 -m venv venv
source venv/bin/activate
pip3 install kittycad
python3 tutorials/beginner_tutorial/convert.py

Replace YOUR-API-TOKEN with one of your API tokens. It looks like you need to generate an API Token first.

As long as everything went smoothly, you will see the following output (Note: your STL file will be called output.stl and be placed in the same directory):

File conversion id: <your-conversion-id>
File conversion status: Completed
Saving output to ./output.stl

Note: depending on the version of Python you have installed, the "Python3" command might differ.

Congrats! You just made your first successful API command using a Python script. We offer plenty of API endpoints for you to use (file conversions, calculating center of mass, converting units, and more). Check them out here.

Click on the button below to see the script we ran.

convert.py script

Windows

Once you download the .zip file and place it somewhere you can easily access, extract the contents of your zip file. You can do this by double-clicking on the file. This will unpack the zip file and place a new folder called litterbox-main with all the contents into your directory.
Install the latest version of Python for your machine here: Install Python
- make sure you download the correct version for Windows
Once you download Python, you will need to open your Powershell. One way to open the Powershell is to click on the Start button and type "powershell" and press enter
Once Powershell is open, you will need to navigate to the folder in which you put all the files. As an example, let's say you put them on the Desktop. You would type the following in Powershell and hit enter:

cd ~/Desktop/litterbox-main

cd ~/Documents/ZooPractice/litterbox-main

You will now be working inside the litterbox-main folder you placed inside the ZooPractice folder.

Another method for changing directories is if you see the folder you want to move into (whether through File Explorer or the Desktop), you can type "cd" and then just drag and drop the folder onto Powershell, it will automatically fill out the file path for you. Just hit "enter".

You will now be working inside the folder you created called ZooPractice.

Once inside the correct folder, input the following commands into Powershell. (Note: if you are signed in and have made an API token, we auto-populated your token below). Simply copy and paste the following:

export KITTYCAD_API_TOKEN="YOUR-API-TOKEN"
pip3 install virtualenv
python3 -m venv venv
source venv/bin/activate
pip3 install kittycad
python3 tutorials/beginner_tutorial/convert.py

Replace YOUR-API-TOKEN with one of your API tokens. It looks like you need to generate an API Token first.

As long as everything went smoothly, you will see the following output (Note: your STL file will be called output.stl and be placed in the same directory):

File conversion id: <your-conversion-id>
File conversion status: Completed
Saving output to ./output.stl

Note: depending on the version of Python you have installed, the "Python3" command might differ.

Click on the button below to see the script we ran.

convert.py script

Linux

Once you download the .zip file and place it somewhere you can easily access, extract the contents of your zip file. You can do this by double-clicking on the file. This will unpack the zip file and place a new folder called litterbox-main with all the contents into your directory.
Install the latest version of Python for your machine here: Install Python
- make sure you download the correct version for Linux
Once you download Python, you will need to open your Terminal. There are a few ways to open the Terminal:
- Press "CTRL" + "ALT" + "T"
- Click the Terminal icon amongst the list of all apps.
Once the Terminal is open, you will need to navigate to the folder in which you put all the files. As an example, let's say you put them on the Desktop. You would type the following in your Terminal and hit "enter":

cd ~/Desktop/litterbox-main

cd stands for change directory. Once you hit return, you will be working inside the Desktop. For another example, let's say you put your files in a folder called ZooPractice within the Documents folder. This would look like so:

cd ~/Documents/ZooPractice/litterbox-main

You will now be working inside the litterbox-main folder you placed inside the ZooPractice folder.

Another method for changing directories is if you see the folder you want to move into, you can type "cd" and then just drag and drop the folder onto Terminal, it will automatically fill out the file path for you. Just hit "return".

You will now be working inside the folder you created called ZooPractice.

Once inside the correct folder, input the following command into Terminal. (Note: if you are signed in and have made an API token, we auto-populated your token below). Simply copy and paste the following:

export KITTYCAD_API_TOKEN="YOUR-API-TOKEN"
pip3 install virtualenv
python3 -m venv venv
source venv/bin/activate
pip3 install kittycad
python3 tutorials/beginner_tutorial/convert.py

Replace YOUR-API-TOKEN with one of your API tokens. It looks like you need to generate an API Token first.

As long as everything went smoothly, you will see the following output (Note: your STL file will be called output.stl and be placed in the same directory):

File conversion id: <your-conversion-id>
File conversion status: Completed
Saving output to ./output.stl

Note: depending on the version of Python you have installed, the "python3" and "pip3" command might differ.

convert.py script

from typing import Dict, Optional, Union

from kittycad.api.file import create_file_conversion
from kittycad.client import ClientFromEnv
from kittycad.models import Error, FileConversion
from kittycad.models.base64data import Base64Data
from kittycad.models.file_export_format import FileExportFormat
from kittycad.models.file_import_format import FileImportFormat
from kittycad.types import Unset


# Create a new function to convert an OBJ file to an STL file.
def convertOBJtoSTL():
    # Create a new client with your token parsed from the environment variable (KITTYCAD_API_TOKEN)
    client = ClientFromEnv(timeout=500, verify_ssl=True)

    # Read in the contents of the file.
    file = open("./dodecahedron.obj", "rb")
    content = file.read()
    file.close()

    # Call the create_file_conversion function with the required parameters: client, body, src_format, and output_format.

    result: Optional[Union[Error, FileConversion]] = create_file_conversion.sync(
        client=client,  # The client you created above.
        body=content,  # The contents of the file you read in.
        src_format=FileImportFormat.OBJ,  # The format of the file you read in.
        output_format=FileExportFormat.STL,  # The format you want to convert to.
    )

    # Check if the result is an error or None.
    if isinstance(result, Error) or result is None:
        raise Exception("There was a problem")

    body: FileConversion = result
    if isinstance(body.outputs, Unset):
        raise Exception("Expected outputs to be set")

    # Loop through the outputs and save them to a file.
    outputs: Dict[str, Base64Data] = body.outputs

    for _, output in outputs.items():
        output_file_path = "./dodecahedron.stl"
        print(f"Saving output to {output_file_path}")
        output_file = open(output_file_path, "wb")
        output_file.write(output.get_decoded())
        output_file.close()
    return body


convertOBJtoSTL()

Found a typo?