Rodin Generation

Rodin: The all in one API for generating Rodin. This API will generate a mesh and textures for the given images and prompt. This API provide two tiers of generation, Sketch and Regular. Sketch is optimized for generation speed, and is recommended for fast prototyping. Regular is optimized for quality, and is recommended for production.

POST/api/v2/rodin

Authorization

bearer

Body

multipart/form-data

imagestring (binary)

promptstring

seednumber

geometry_file_formatenum

glbusdzfbxobjstl

materialenum

PBRShaded

qualityenum

highmediumlowextra-low

use_hyperboolean

tierenum

RegularSketch

addonsarray of enum

Response

201

Body

application/json

errorstring

messagestring

uuidstring

jobsobject

Request

JavaScriptCurlPython

const response = await fetch('/api/v2/rodin', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

201

{
  "error": "text",
  "message": "text",
  "uuid": "text",
  "jobs": {
    "uuids": [
      "text"
    ],
    "subscription_key": "text"
  }
}

Rodin Generation

Use this API to submit an asynchronous task to our server. You will get a task UUID from the API which can be used to check the status of the the task and download the result when the task is ready.

Pricing

Note: There are no additional fees for parameters. Only addons incur extra charges.

• Base Cost: 0.5 credit per generation for both Sketch and Regular tier.

• Addons:

  • HighPack: Additional 1 credit per generation.

Request

Note: All requests to this endpoint must be sent using multipart/form-data to properly handle the file uploads and additional parameters required for the mesh and texture generation process.

Authentication

This API uses bearer key for authentication. You need to include a valid token in the Authorization header for all requests. Refer to the Quickstart section for how to generate an API key for your account.

Authorization: Bearer RODIN_API_KEY

Body

Parameter	Type	Description
images	file/Binary/base64	Images to be used in generation, up to 5 images. As the form data request will preserve the order of the imgaes, the first image will be the image for material generation. Required. For Image-to-3D generate mode. One or more images are needed.(Maximum of 5 images.) NULL. For Text-to-3D generate mode.
prompt	string	A textual prompt to guide the model generation. If not provided, an AI-generated prompt based on the provided images will be used. Optional. For Image-to-3D generate mode. Required. For Text-to-3D generate mode.
condition_mode	string	Optional. Generation mode of Rodin API. Possible values are fuse and concat. Default is concat. For fuse mode, One or more images are required.It will generate a model by extracting and fusing features of objects from multiple images. For concat mode, need to upload multiple multi-view images of the same object and generate the model.(You can upload multi-view images in any order, regardless of the order of view.)
seed	number	Optional. A seed value for randomization in the mesh generation, ranging from 0 to 65535 (both inclusive). If not provided, the seed will be randomly generated.
geometry_file_format	string	Optional. Format of the geometry file. Possible values are glb, usdz, fbx, obj, and stl. Default is glb. For Rodin Sketch, the value should either remain unset or be set to glb.
material	string	Optional. The material type. Possible values are PBR and Shaded. Default is PBR. For Rodin Sketch, the value should either remain unset or be set to PBR.
quality	string	Optional. The generation quality. Possible values are high, medium, low, and extra-low. Default is medium. For Rodin Sketch, the value should either remain unset or be set to medium.
use_hyper	boolean	Optional. Whether the generated model should be exported using hyper mode. Default is false. For Rodin Sketch, the value should either remain unset or be set to false.
tier	string	Optional. Tier of generation. For Rodin Sketch, the value should be set to Sketch. For Rodin Regular, the value shouid either remain unset or be set to Regular.
TAPose	bool	Optional. When generating the human-like model, this parameter control the generation result to T/A Pose.
bbox_condition	Array of Integer	Optional. An array that specifies the dimensions and scaling factor of the bounding box. Typically, this array contais 3 elements, Length(X-axis), Width(Y-axis) and Height(Z-axis).
addons	array of strings	Optional. Generation add-on features. Default is []. Possible values are HighPack. The HighPack option will provide 4K resolution textures instead of the default 1K, as well as models with high-poly.

Rodin provides two generation modes: Text-to-3D and Image-to-3D. Image-to-3D: When you upload Image files, Rodin will automatically select Image-to-3D mode and you can upload one or more image files. When Multiple images are uploaded,

• fuse mode will combine all the features of the image to generate.

• And concat mode expects these images to be multi-view images of a single model. As the form data request will preserve the order of the images, the first image will be the image for material generation.

Text-to-3D: When you have not uploaded any image files, you must upload the "prompt" parameter and Rodin will change to Text-to-3D mode.

ControlNet: ControlNet enhances model customization by providing finer control over the generated outputs. It adds several parameters on top of the original API, allowing users to manipulate aspects such as proportions, shapes, and structures of 3D models.

ControlNet introduces the following main parameters to provide advanced control over the model generation process:

• BoundingBox ControlNet: The BoundingBox ControlNet allows users to define the proportions of the generated model by specifying the length, width, and height through a draggable bounding box. This is particularly useful when you want the generated object to fit within specific dimensions or adhere to certain spatial constraints.

  • Example Representation:

    {
    "bbox_condition": [
      	100,
      	100,
      	100
      ]
    }

  • bbox_condition: An array that specifies the dimensions and scaling factor of the bounding box.

    • Elements:

      1. Length (X-axis):100 units.

      2. Width (Y-axis):100 units.

      3. Height (Z-axis):100 uints.

    By setting the bbox_condition, you're instructing the model to generate an object that fits within a box of the specified dimensions.

  • Bounding Box Axis:

          World               
    
        +z(Height)                                                    
        |                                                
        |                                                        
        |______+y(Width)        
        /                  
       /                      
      /                          
      +x(Length)                        

Response

Use the uuid field instead of the jobs.uuids field for your requests to Check Status and Download Results API endpoints.

Property	Type	Description
error	string	Error message, if any.
message	string	Success message or detailed error information.
uuid	string	Unique identifier for the generated task.
jobs	object	A job object, containing details of individual jobs executed as part of the generation process.
jobs.uuids	array of strings	UUIDs of the sub-jobs.
jobs.subscription_key	string	Subscription key associated with these jobs.

Examples

Minimal Rodin Regular Generation(Image-to-3D)

Request with cURL

export RODIN_API_KEY="your api key"
curl https://hyperhuman.deemos.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F "images=@/path/to/your/image.jpg"  
unset RODIN_API_KEY

Request with Python 3

import os
import requests

# Constants
ENDPOINT = "https://hyperhuman.deemos.com/api/v2/rodin"
API_KEY = "your api key"  # Replace with your actual API key
IMAGE_PATH = "/path/to/your/image.jpg"  # Replace with the path to your image

# Prepare the multipart form data
files = [
	('images', open(IMAGE_PATH, 'rb')),
]

# Prepare the headers
headers = {
    'Authorization': f'Bearer {API_KEY}',
}

# Make the POST request
response = requests.post(ENDPOINT, files=files, headers=headers)

# Parse and return the JSON response
print(response.json())

Request with Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"mime/multipart"
	"net/http"
	"os"
	"path/filepath"
)

const BaseURI = "https://hyperhuman.deemos.com/api"

type CommonError struct {
	Error   *string `json:"error,omitempty"`
	Message *string `json:"message,omitempty"`
}

type JobSubmissionResponse struct {
	Uuids           []string `json:"uuids"`
	SubscriptionKey string   `json:"subscription_key"`
}

type RodinAllInOneResponse struct {
	CommonError
	Uuid *string                 `json:"uuid,omitempty"`
	Jobs JobSubmissionResponse   `json:"jobs,omitempty"`
}

func RunRodin(token string, filePath string) (*RodinAllInOneResponse, error) {
	var err error
	var buffer bytes.Buffer

	// Create the form data for Rodin API
	writer := multipart.NewWriter(&buffer)

	// Read the image
	image, err := os.ReadFile(filePath)
	if err != nil {
		return nil, err
	}

	// Add the image as a form entry
	fieldWriter, err := writer.CreateFormFile("images", filepath.Base(filePath))
	if err != nil {
		return nil, err
	}

	if _, err = fieldWriter.Write(image); err != nil {
		return nil, err
	}

	err = writer.Close()
	if err != nil {
		return nil, err
	}

	// Create the request
	req, err := http.NewRequest("POST", fmt.Sprintf("%s/v2/rodin", BaseURI), &buffer)
	if err != nil {
		return nil, err
	}

	// Set headers
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", writer.FormDataContentType())

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var responseData RodinAllInOneResponse
	err = json.NewDecoder(resp.Body).Decode(&responseData)
	if err != nil {
		return nil, err
	}

	if responseData.Error != nil {
		return nil, fmt.Errorf("%s: %s", *responseData.Error, *responseData.Message)
	}

	return &responseData, nil
}

func main() {
        // Replace with your actual API key
	token := "your api key"
	// Replace with the path to your image
	resp, _ := RunRodin(token, "/path/to/your/image.jpg")
	fmt.Println(resp)
}

Response

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

Minimal Rodin Sketch Generation(Image-to-3D)

Request with cURL

export RODIN_API_KEY="your api key"
curl https://hyperhuman.deemos.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F "images=@/path/to/your/image.jpg" \
  -F "tier=Sketch" 
unset RODIN_API_KEY

Request with Python 3

import os
import requests

# Constants
ENDPOINT = "https://hyperhuman.deemos.com/api/v2/rodin"
API_KEY = "your api key"  # Replace with your actual API key
IMAGE_PATH = "/path/to/your/image.jpg"  # Replace with the path to your image

# Read the image file
with open(IMAGE_PATH, 'rb') as image_file:
    image_data = image_file.read()

# Prepare the multipart form data
# Set the tier to Rodin Sketch
files = {
    'images': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg'),
	'tier':(None, 'Sketch'),
}

# Prepare the headers
headers = {
    'Authorization': f'Bearer {API_KEY}',
}

# Make the POST request
response = requests.post(ENDPOINT, files=files, headers=headers)

# Parse and return the JSON response
print(response.json())

Request with Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"mime/multipart"
	"net/http"
	"os"
	"path/filepath"
)

const BaseURI = "https://hyperhuman.deemos.com/api"

type CommonError struct {
	Error   *string `json:"error,omitempty"`
	Message *string `json:"message,omitempty"`
}

type JobSubmissionResponse struct {
	Uuids           []string `json:"uuids"`
	SubscriptionKey string   `json:"subscription_key"`
}

type RodinAllInOneResponse struct {
	CommonError
	Uuid *string                 `json:"uuid,omitempty"`
	Jobs JobSubmissionResponse   `json:"jobs,omitempty"`
}

func RunRodin(token string, filePath string) (*RodinAllInOneResponse, error) {
	var err error
	var buffer bytes.Buffer

	// Create the form data for Rodin API
	writer := multipart.NewWriter(&buffer)

	// Read the image
	image, err := os.ReadFile(filePath)
	if err != nil {
		return nil, err
	}

	// Add the image as a form entry
	fieldWriter, err := writer.CreateFormFile("images", filepath.Base(filePath))
	if err != nil {
		return nil, err
	}

	if _, err = fieldWriter.Write(image); err != nil {
		return nil, err
	}
	
	// Set the tier to Rodin Sketch
	fieldWriter, err = writer.CreateFormField("tier")
	if err != nil {
		return nil, err
	}

	if _, err = fieldWriter.Write([]byte("Sketch")); err != nil {
		return nil, err
	}

	err = writer.Close()
	if err != nil {
		return nil, err
	}

	// Create the request
	req, err := http.NewRequest("POST", fmt.Sprintf("%s/v2/rodin", BaseURI), &buffer)
	if err != nil {
		return nil, err
	}

	// Set headers
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", writer.FormDataContentType())

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var responseData RodinAllInOneResponse
	err = json.NewDecoder(resp.Body).Decode(&responseData)
	if err != nil {
		return nil, err
	}

	if responseData.Error != nil {
		return nil, fmt.Errorf("%s: %s", *responseData.Error, *responseData.Message)
	}

	return &responseData, nil
}

func main() {
        // Replace with your actual API key
	token := "your api key"
	// Replace with the path to your image
	resp, _ := RunRodin(token, "/path/to/your/image.jpg")
	fmt.Println(resp)
}

Response

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

Minimal Rodin Generation(Text-to-3D)

Request with cURL

export RODIN_API_KEY="your api key"
curl https://hyperhuman.deemos.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F "prompt=A 3D model of a futuristic robot" \
unset RODIN_API_KEY

Response

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

Minimal Rodin Generation(Image-to-3D with multi-view images)

Request with cURL

export RODIN_API_KEY="your api key"
curl https://hyperhuman.deemos.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F 'condition_mode=concat' \
  -F "images=@/path/to/your/image_0.jpg" \
  -F "images=@/path/to/your/image_1.jpg" 
unset RODIN_API_KEY

Request with Python 3

import os
import requests

# Constants
ENDPOINT = "https://hyperhuman.deemos.com/api/v2/rodin"
API_KEY = "your api key"  # Replace with your actual API key
IMAGE_PATH_0 = "/path/to/your/image_0.jpg"  # Replace with the path to your image_0
IMAGE_PATH_1 = "/path/to/your/image_1.jpg"  # Replace with the path to your image_1

# Prepare the multipart form data
files = [
	('images', open(IMAGE_PATH_0, 'rb')),
	('images', open(IMAGE_PATH_1, 'rb')),
]

# Prepare the headers
headers = {
    'Authorization': f'Bearer {API_KEY}',
}

# Make the POST request
response = requests.post(ENDPOINT, files=files, headers=headers)

# Parse and return the JSON response
print(response.json())

Response

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

Minimal Rodin ControlNet Generation(Bounding Box Condition)

Request with cURL

export RODIN_API_KEY="your api key"
curl https://hyperhuman.deemos.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F "bbox_condition=[100,100,100]"
  -F "prompt=A sofa."
unset RODIN_API_KEY

Request with Python 3

import os
import requests

# Constants
ENDPOINT = "https://hyperhuman.deemos.com/api/v2/rodin"
API_KEY = "your api key"  # Replace with your actual API key
IMAGE_PATH = "/path/to/your/image.jpg"  # Replace with the path to your image

# Read the image file
with open(IMAGE_PATH, 'rb') as image_file:
    image_data = image_file.read()

# Prepare the images data
# Prepare the Bounding Box data
files = {
    'images': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg'),
	'bbox_condition':(None, [100, 100, 100]),
}

# Prepare the headers
headers = {
    'Authorization': f'Bearer {API_KEY}',
}


# Make the POST request
response = requests.post(ENDPOINT, files=files, data=data, headers=headers)

# Parse and return the JSON response
print(response.json())

Response

{
  "error": null,
  "message": "Submitted. Please check progress via /api/v2/status and get download link via /api/v2/download",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

Comprehensive Rodin Regular Generation with All Parameters

Request with cURL

export RODIN_API_KEY="your api key"
curl https://hyperhuman.deemos.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F "images=@/path/to/your/image.jpg" \
  -F "prompt=A 3D model of a futuristic robot" \
  -F "seed=42" \
  -F "geometry_file_format=fbx" \
  -F "material=PBR" \
  -F "quality=high" \
  -F "use_hyper=true" \
  -F "tier=Regular" \
  -F "addons=HighPack"
unset RODIN_API_KEY

Response

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}