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生成

使用此API向我们的服务器提交异步任务。你将从API中获得一个任务UUID，该UUID可用于检查进度和下载结果。

价格

Note: 参数不会收取任何额外费用，只有模型附加项才会有额外收费。

• Base Cost: `Sketch`和`Regular`每次生成消耗 0.5 Credit。

• Addons:

  • HighPack: 每次生成额外消耗 1 Credit。

请求

Note: 所有到这个端点的请求都必须使用multipart/form-data发送，以正确处理文件上传以及网格和纹理生成过程所需的其他参数。

Authentication

此API使用密钥进行身份验证。您需要在所有请求的Authorization头中包含一个有效的密钥. 参阅快速开始获取您的账户的API生成密钥。

Authorization: Bearer RODIN_API_KEY

Body

参数	类型	描述
images	file	用于图像生成，最多上传5张图片。由于form-data请求将保留图像的顺序，因此将会使用上传列表的第一张图片来生成材质贴图。 对于Image-to-3D模式，图片是必须的。可上传一张或多张图片。（最多上传5张图片。） 对于Text-to-3D模式，则不需要上传图片。
prompt	string	用于指导模型生成的文本提示。如果没有提供，将使用基于提供的图像的人工智能生成的提示。 对于Image-to-3D生成模式是可选的。 对Text-to-3D模式是必须的
condition_mode	string	可选的。Rodin API的生成模式。可能的值为fuse或concat。默认值为concat。 对于fuse 模式，需要上传一张或多张图片。可以融合多张图片的物体特征生成一个模型。 对于concat模式，需要上传同一物体的多张多视角图片，并生成该模型。（无须在意）
seed	number	可选的。网格生成中用于随机化的种子值，范围从0到65535(包括两者)。如果不提供，种子将随机生成。
geometry_file_format	string	可选的。模型文件的格式。可能的值为glb，usdz，fbx，obj，stl。默认值为glb。 对于Rodin Sketch，该值要么保持不设置，要么设置为glb。
material	string	可选的。材质类型。可能的值为PBR和shade。默认值为PBR。 对于Rodin Sketch，该值应该保持未设置或设置为PBR。
quality	string	可选的。生成质量。可能的值为high, medium, low, 和extra-low。默认值为medium。 对于Rodin Sketch，该值要么保持不设置，要么设置为medium。
use_hyper	boolean	可选的。是否应该使用hyper模式导出生成的模型。默认值为false 对于Rodin Sketch，该值应该保持未设置或设置为false。
tier	string	可选的。生成层级。 对于Rodin Sketch，该值应该设置为Sketch。 对于Rodin Regular，该值保持不设置或设置为Regular。
TAPose	bool	可选的。控制生成类人模型时，生成结果展现为T/A Pose。
bbox_condition	Array of Integer	可选的。用于指定边界框的尺寸喝缩放系数的一个数组。 通常来说，这个数组包含三个元素，分别是长度（x轴），宽度（y轴）和高度（z轴）。
addons	array of strings	可选的。生成附加功能。默认为[]。可能的值为HighPack. HighPack选项会提供4K分辨率的纹理贴图而不是基础的1K分辨率，同时还会提供更高面数的模型文件。

Rodin提供两种生成模式: Text-to-3D 和 Image-to-3D. Image-to-3D: 当你将图片文件作为参数上传，Rodin会执行Image-to-3D生成，您可以上传一张或多张图片。当上传多张图片时，

• fuse模式将融合图片特征来生成模型。

• concat模式需要您上传同一事物的多张多视角图片用于生成。

Text-to-3D: 当您没有上传任何图片文件，Rodin会执行Text-to-3D生成，您必须上传Prompt参数。

ControlNet: ControlNet通过对生成的输出提供更精细的控制来增强模型定制。它在原始API的基础上添加了几个参数，允许用户操作3D模型的比例、形状和结构等方面。

ControlNet引入以下主要参数，以提供对模型生成过程的高级控制：

• BoundingBox ControlNet: BoundingBox ControlNet允许用户通过可拖动的边界框指定长度、宽度和高度来定义生成模型的比例。当您希望生成的对象适合特定的尺寸或遵循特定的空间约束时，这尤其有用。

  • 样例：

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

  • bbox_condition: 指定边界框的尺寸和缩放因子的数组。

    • 元素:

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

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

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

    通过设置 bbox_condition，您将指示模型生成一个适合指定尺寸的长方体对象。

  • Bounding Box Axis:

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

响应

对于response from the Generation API的task_uuid，使用uuid字段替代jobs_uuid。

Property	Type	Description
error	string	错误信息（如有）
message	string	成功信息或详细的错误信息。
uuid	string	生成任务的唯一标识符。
jobs	object	一个作业对象，包含作为生成过程一部分执行的各个作业的详细信息。
jobs.uuids	array of strings	子任务的UUIDs。
jobs.subscription_key	string	任务密钥

代码示例

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
files = {
    'images': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg')
}

# Set the tier to Rodin Sketch
data = {
    'tier': 'Sketch',
}

# 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())

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
files = {
    'images': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg')
}

# Prepare the Bounding Box data
data = {
    "bbox_condition":[
		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"
  }
}