Rodin Generation

The all in one API for generating Rodin.

post

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.

授权

请求体

imagesstring · binary必填

promptstring可选

condition_modestring · enum可选Default: concat可能的值:

seednumber可选

geometry_file_formatstring · enum可选Default: glb可能的值:

materialstring · enum可选Default: PBR可能的值:

qualitystring · enum可选Default: medium可能的值:

use_hyperboolean可选Default: false

tierstring · enum可选可能的值:

TAPoseboolean可选Default: false

bbox_conditionarray可选Default: []

mesh_modestring · enum可选Default: Quad可能的值:

mesh_simplifyboolean可选Default: true

mesh_smoothboolean可选Default: true

响应

201成功

application/json

post

CLI

curl https://hyperhuman.deemos.com/api/v2/rodin \
--request POST \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: multipart/form-data' \
--file 'images=@/path/to/your/image.png' \
--file "tier=Regular" \ 
...

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/Binary	用于图像生成，最多上传5张图片。由于form-data请求将保留图像的顺序，因此将会使用上传列表的第一张图片来生成材质贴图。 对于Image-to-3D模式，图片是必须的。可上传一张或多张图片。（最多上传5张图片。） 对于Text-to-3D模式，则不需要上传图片。
prompt	string	用于指导模型生成的文本提示。 对于Image-to-3D生成模式是可选的。(如果没有提供，将使用基于提供的图像的人工智能生成的提示。) 对Text-to-3D模式是必须的。
condition_mode	string	该参数仅用于多图像生成。 这是一个可选的参数，用于选择多图生成时的生成方式。可能的值为fuse或concat。默认值为concat。 对于fuse 模式，需要上传一张或多张图片。可以融合多张图片的物体特征生成一个模型。 对于concat模式，需要上传同一物体的多张多视角图片，并生成该模型。（无须在意上传图片的顺序。）
seed	number	可选的。网格生成中用于随机化的种子值，范围从0到65535(包括两者)。如果不提供，种子将随机生成。
geometry_file_format	string	可选的。模型文件的格式。可能的值为glb，usdz，fbx，obj，stl。默认值为glb。
material	string	可选的。材质类型。可能的值为PBR和shade。默认值为PBR。 对于Rodin Sketch，该值仅为PBR时生效。
quality	string	可选的。生成质量。可能的值为high(50k面), medium(18k面), low(8k面), 和extra-low(4k面)。默认值为medium。 对于Rodin Sketch，该值仅为medium时生效。
use_hyper	boolean	可选的。默认值为false 在生成具有更精细结构的对象时，将use_hyper设置为true，则3D模型的质量会更好。 对于Rodin Sketch，该值仅为false时生效。
tier	string	可选的。默认值为Regular。 Sketch：快速生成，细节较少，适合概念草图或初步构思。 Regular：平衡生成速度与质量，适用于大多数场景（默认选项）。 Detail：比 Regular 更丰富的细节表现，适合复杂需求（生成时间更长）。 Smooth：比 Regular 更清晰锐利的输出效果，生成时间略长。
TAPose	bool	可选的。控制生成类人模型时，生成结果展现为T/A Pose。 当该值为true时，生成的模型将为Tpose或者Apose。
bbox_condition	Array of Integer	可选的。该参数是一个控制生成模型最大生成边界的control net. 通常来说，这个数组包含三个元素，分别是宽度（y轴），高度（z轴）和长度（x轴）。
mesh_mode	string	可选的，可选的值有Raw和Quad. 默认值为Quad. Raw模式会生成三角面模型。 Quad模式生成四边面模型。
mesh_simplify	bool	可选的。当值为true时，将会生成简化模型。 该参数仅当mesh_mode的值为Raw时生效。并且当该参数的值为true时，其他所有可选参数均设置为默认值。
addons	array of strings	可选的。生成附加功能。默认为[]。可能的值为HighPack. HighPack选项会提供4K分辨率的纹理贴图而不是基础的2K分辨率，同时还会提供更高面数的模型文件。

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. Width (Y-axis):100 units.

      2. Height (Z-axis):100 units.

      3. Length (X-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
# 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, 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"
  }
}