Quickstart to generating 3D models

Prerequisites

Follow the instructions here to ensure you have:

An account set up
An API KEY
The MPX SDK installed
Sufficient generation credits

Click on the 'Putting it all together' section (on the right sidebar) for ready to use copy-paste code.

Keep reading to go through the code in a step-by-step manner.

Importing the SDK

Once you have completed the setup above, you can import the SDK in Python as follows:

from mpx_genai_sdk import Masterpiecex

client = Masterpiecex(bearer_token=os.environ.get("MPX_SDK_BEARER_TOKEN"))

The client instance interacts with the API to perform various functions, such as creating generation requests, uploading assets, and checking request statuses.

Generating an image from text

You can generate an image from text as follows:

text_to_image_request = mpx_client.components.text2image(
  prompt= "Cute cartoon brown dog with a big head. Candid, full body view, side camera angle.  White matte background with bright, indirect lighting",
  num_images= 4,
  num_steps= 4,
  lora_id="mpx_game"
)

Key points:

The data returned (text_to_image_request) is not the images themselves but a GenerateResponseObject. This object contains three fields:
- balance: Displays the remaining generation credits on your account.
- request_id: A unique string identifier that allows you to query the request's status.
- status: The current status of your request at the moment the function is called. You will need to poll the API using (request_id) to retrieve the updated status.
For thetext2imagecomponent:
- The maximum number of images that can be generated per API call is 4.
- The maximum number of diffusion steps allowed per request is 4.
You can specify a LoRA ID to style the image in a particular manner. Valid values include:
- mpx_game
- mpx_iso
- mpx_plush
  More LoRA options will be added over time—stay tuned!

For more details on this component and all the additional parameters see: https://docs.masterpiecex.com/reference/post_components-text2image-1#/

Polling a request

Once we have the GenerateResponseObject , we can poll it's status to determine if the request is complete. Below is an example function to check request status:

import time

# Get the status of a Request
# Wait until the object has been generated (status = 'complete')
def retrieve_request_status(mpx_client, request_id):
  status_response = mpx_client.status.retrieve(request_id)
  print(status_response)
  # Wait until the object has been generated (status = 'complete')
  while status_response.status not in ["complete", "failed"]:
    time.sleep(10)
    status_response = mpx_client.status.retrieve(request_id)
    print ('*', end='')
    print('') # clears waiting indicators
    print(status_response)
    return status_response

Using our text_to_image_request that was created earlier, we would call the above function as follows:

text_to_image_response = retrieve_request_status(mpx_client, text_to_image_request.request_id)

Once retrieve_request_status completes, it returns aStatusResponseObject. Logging this object to the console would display an output similar to:

StatusResponseObject(outputs=Outputs(fbx=None, glb=None, thumbnail=None, usdz=None, 
                                     zip='https://storage.googleapis.com/.../output.zip', 
                                     images=['https://storage.googleapis.com/.../output_image_0.png', 
                                             'https://storage.googleapis.com/.../output_image_1.png', 
                                             'https://storage.googleapis.com/.../output_image_2.png', 
                                             'https://storage.googleapis.com/.../output_image_3.png']
                                    ), 
                     output_url=None, 
                     processing_time_s=3.141592, 
                     progress=None, 
                     request_id='<your-request-id>', 
                     status='complete', 
                     requestId='<your-request-id>', 
                     processingTime_s=3.141592)

Since we are generating images, the key outputs to retrieve are the image URLs stored in the images list in the outputs field.

Retrieving the generated result

To download the generated images from a completed request, use the following code:

import requests
from io import BytesIO
from PIL import Image

num_of_images = len(text_to_image_response.outputs.images)
actual_img_data = []
output_folder = "<path to desired folder>"
for i in range(num_of_images):
  img_response = requests.get(text_to_image_response.outputs.images[i])
  img = Image.open(BytesIO(img_response.content))
  img.save(f"{output_folder}/result_{i}.png")
  actual_img_data.append(img)

Key points:

The URLs returned from the API are used to download images one by one using the requestslibrary.
The downloaded content is converted into image data using pillow, the Python Image Processing library. You can install pillow via pip install pillow.
The requests.get() function is used in this code block. It requires the requests Python package. You can install requests via pip install requests.
The images are saved to disk in the specified output folder. (provided you update the output_folder variable) and are also stored in a list for possible future use.

Uploading an image as an asset for 3D generation

In order to generate 3D models from images, you need to first upload an image to our system for processing. This can be done as follows:

# Create asset ID for the image
asset_response = mpx_client.assets.create(
  description="A description of the image",
  name="image1.png",
  type="image/png",
)
print(asset_response)
print(f'asset_url: {asset_response.asset_url}')
print(f'request_id: {asset_response.request_id}')

headers = {
  'Authorization': f'Bearer {os.environ.get("MPX_SDK_BEARER_TOKEN")}',
  'Content-Type': 'image/png',
}

# Open the image file in binary mode and upload it
fpath_image = f"{output_folder}/result_0.png" # replace with a filepath to an image of your own
with open(fpath_image, 'rb') as image_file:
  image_data = image_file.read()
  upload_response = requests.put(asset_response.asset_url, data=image_data, headers=headers)  
  
# Print the response from the server
print(upload_response.status_code)
print(upload_response.text)

Key points:

When calling mpx_client.assets.create we are creating a temporary location on our servers where the actual image data will be uploaded to. The returned response will include a URL (asset_url field) that we will use to upload the actual data and the unique request_id of this asset creation request.

Once we have the URL to upload our desired image to, we can upload the image by reading the data contents of the image as bytes and then uploading the data using the requests library. Note that the header requires the bearer token and we also set the Content-Type to be image/png.

If the upload is successful, the status_code of the returned response object should be 200.

Generating a 3D model from an image

Now that we have uploaded an image to the server we can take the request_id that we obtained as part of the response and use that to call the imageto3d function in the MPX SDK.

imageto3d_request = mpx_client.functions.imageto3d(
  image_request_id = asset_response.request_id,
  seed=1,
  texture_size=1024
)
print(imageto3d_request)
print(f'imageto3d_request.request_id: {imageto3d_request.request_id}')

imageto3d_status_response  = retrieve_request_status(mpx_client, imageto3d_request.request_id)
print(f'imageto3d_status_response: {imageto3d_status_response}')

Key points:

Note that you can alter the seed value for different generations per image and the texture_size should be a value that is either 512, 1024, 2048. You may encounter an error if you use values which are not a power of 2 and you may encounter long runtimes (or errors) for values larger than 2048.

Similar to text2image we call the retrieve_request_status to keep checking the status of the request until it is finished. The output, imageto3d_status_response will once again be a StatusResponseObject and when logged to the console it will look something like the following:

StatusResponseObject(outputs=Outputs(
  fbx='https://storage.googleapis.com/.../output.fbx', 
  glb='https://storage.googleapis.com/.../output.glb', 
  thumbnail='https://storage.googleapis.com/.../thumbnail.png', 
  usdz='https://storage.googleapis.com/.../output.usdz'
), 
                     output_url=None, 
                     processing_time_s=37.244, 
                     progress=None, 
                     request_id='<your request id>', 
                     status='complete', 
                     requestId='<your request id>', 
                     processingTime_s=37.244)

The URLs of generated 3D model in different file formats will be in the fields fbx, glb and usdz. The field thumbnail is a rendering of the model so you can see a preview of what it might look like without opening the model itself.

Here is an example of how you might download the model from the URL and write it to disk:

model_url = "https://storage.googleapis.com/.../output.glb"
fpath_model = "<folder name>/<file name>.glb"

model_response = requests.get(model_url)
with open(fpath_model, "wb") as model_file:
	model_file.write(model_response.content)

Putting it all together

Here is the complete script putting all the steps above together.

import os
import time
import requests
from io import BytesIO
from PIL import Image

from mpx_genai_sdk import Masterpiecex

# Get the status of a Request
# Wait until the object has been generated (status = 'complete')
def retrieve_request_status(mpx_client, request_id):
    status_response = mpx_client.status.retrieve(request_id)
    print("\n[Initial Status]")
    print(status_response)
    
    # Wait until the object has been generated (status = 'complete')
    while status_response.status not in ["complete", "failed"]:
        time.sleep(10)
        status_response = mpx_client.status.retrieve(request_id)
        print('*', end=' ')
    
    print("\n\n[Final Status]")
    print(status_response)
    return status_response


def run_text2image2model(mpx_client):
    text_to_image_request = mpx_client.components.text2image(
        prompt="Cute cartoon brown dog with a big head. Candid, full body view, side camera angle.  White matte background with bright, indirect lighting",
        num_images=4,
        num_steps=4,
        lora_id="mpx_game"
    )

    # Wait for request to complete
    print("\n[Text-to-Image Request]")
    print(text_to_image_request)
    print()

    text_to_image_response = retrieve_request_status(mpx_client, text_to_image_request.request_id)
    print("\n[Image List]")
    print(f'image list: {text_to_image_response.outputs.images}')

    num_of_images = len(text_to_image_response.outputs.images)
    output_folder = "."  # save directly to where this script lives
    actual_img_data = []
    for i in range(num_of_images):
        response = requests.get(text_to_image_response.outputs.images[i])
        img = Image.open(BytesIO(response.content))
        img.save(f"{output_folder}/result_{i}.png")
        actual_img_data.append(img)

    # Create asset ID for the image
    asset_response = mpx_client.assets.create(
        description="test image",
        name="image1.png",
        type="image/png",
    )
    print("\n[Asset Response]")
    print(asset_response)
    print(f'asset_url: {asset_response.asset_url}')
    print(f'request_id: {asset_response.request_id}')

    headers = {
        'Authorization': f'Bearer {os.environ.get("MPX_SDK_BEARER_TOKEN")}',
        'Content-Type': 'image/png',  # Usually not needed with `files`
    }

    # Open the image file in binary mode and upload it
    fpath_image = f"{output_folder}/result_0.png"  # replace with a filepath to an image of your own
    with open(fpath_image, 'rb') as image_file:
        image_data = image_file.read()
        upload_response = requests.put(asset_response.asset_url, data=image_data, headers=headers) 

    # Print the response from the server
    print("\n[Upload Response]")
    print(upload_response.status_code)
    print(upload_response.text)

    # Call imageto3d endpoint with the asset ID
    imageto3d_request = mpx_client.functions.imageto3d(
        image_request_id=asset_response.request_id,
        seed=1,
        texture_size=1024
    )
    print("\n[Image-to-3D Request]")
    print(imageto3d_request)
    print(f'imageto3d_request.request_id: {imageto3d_request.request_id}')

    imageto3d_status_response = retrieve_request_status(mpx_client, imageto3d_request.request_id)
    print("\n[Image-to-3D Status Response]")
    print(f'{imageto3d_status_response}')
    
    # Pick the url to the GLB 3D model and download it to the same output folder as the image
    model_url = imageto3d_status_response.outputs.glb
    fpath_model = f"{output_folder}/model.glb"

    model_response = requests.get(model_url)
    with open(fpath_model, "wb") as model_file:
        model_file.write(model_response.content)


client = Masterpiecex(bearer_token=os.environ.get("MPX_SDK_BEARER_TOKEN"))
run_text2image2model(client)