Gen-1&1.5 Generation

The all in one API for generating Rodin.

post

This API will generate a mesh and textures for the given images and prompt.

授权

Authorizationstring必填

Bearer authentication header of the form Bearer <token>.

请求体

imagesstring · binary可选

promptstring可选

use_original_alphaboolean可选Default: false

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

seednumber可选

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

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

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

quality_overridenumber可选

tierstring · enum可选可能的值:

TAPoseboolean可选Default: false

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

mesh_simplifyboolean可选Default: true

mesh_smoothboolean可选Default: true

preview_renderboolean可选Default: false

响应

201成功

application/json

post

/api/v2/rodin

CLI

curl https://api.hyper3d.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: 每次生成消耗 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模式是必须的。

use_original_alpha

boolean

默认是false. 如果 True, 上传图像的透明度通道将会直接被用于图片处理。

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，Shaded和All。默认值为PBR。 PBR：物理基础材质，包括基础颜色纹理、金属度纹理、法线纹理和粗糙度纹理，提供高真实感并在动态光照下具有物理准确性。 Shaded：仅包含基础颜色纹理和烘焙光照，提供风格化的视觉效果。 All：会同时生成PBR和Shaded材质。

quality

string

可选的。生成质量。可能的值为high(50k面), medium(18k面), low(8k面), 和extra-low(4k面)。默认值为medium。对于Rodin Sketch，该值仅为medium时生效。

quality_override

number

可选的。自定义生成模型的面数。范围从2000到200000面，可对网格面数提供更精确的控制。该参数为quality参数的进阶参数。当调用该参数时，quality参数不会生效。对于Rodin Sketch，该参数不会生效，模型面数设置为quality参数的默认值。

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模式生成四边面模型。当tier为Sketch：仅生成三角面。

mesh_simplify

bool

可选的。当值为true时，将会生成简化模型。该参数仅当mesh_mode的值为Raw时生效。

mesh_smooth

bool

可选的。当值为true时，将会生成平滑模型（效果等同于Rodin Gen-1）。该参数仅当mesh_mode的值为Quad时生效。

addons

array of strings

可选的。生成附加功能。默认为[]。可能的值为HighPack. 当选择HighPack选项时：提供4K分辨率的纹理贴图而不是基础的2K分辨率。当mesh_mode为Quad时，还会提供更高面数的模型文件。(约16倍选择quality对应面数。)

preview_renderbool可选的，默认为false. 如果true，生成结束后的下载列表中将会额外多一张高质量渲染图像。

Rodin 提供了两种生成模式:

Image-to-3D:
当你上传一张或多张 images 时，将会自动启用图生3D模式。
- 单一图片: 上传一张图片来生成3D模型。
- 多图片: 上传多张图片来生成3D模型，此时你还需要考虑如下两种情况：
  fuse 模式: 将你上传的所有图片中物体的特征进行融合，最终生成3D模型。
  concat 模式: 将所有上传图片作为同一物体的多视角图片进行3D模型生成。上传图片的第一张图片将作为贴图生成的参考图。
注意: Form data 请求体会维持你上传图片的顺序，确保你上传图片的顺序正确，尤其是你要使用concat模式的情况下。
Text-to-3D:
当你没有上传任何images时，将自动启用文生3D模式。
- 必须参数:
  prompt: 你必须提供提示词来指导模型的生成。
- 重要: 当时使用Text-to-3D时，请勿输入images参数的值。

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

enum

错误信息（如有）。

message

string

成功信息或详细的错误信息。

uuid

string

生成任务的唯一标识符。

jobs

object

一个作业对象，包含作为生成过程一部分执行的各个作业的详细信息。

jobs.uuids

array of strings

子任务的UUIDs。

jobs.subscription_key

string

任务密钥

Possible Errors include:

Error

描述

NO_ACTIVE_SUBSCRIPTION

没有有效订阅或订阅已经过期。

SUBSCRIPTION_PLAN_TOO_LOW

当前订阅计划等级过低，需要商业计划以使用API功能。

INSUFFICIENT_FUND

用户账户余额不足，无法完成请求的操作。

INVALID_REQUEST

请求格式错误、缺少必要参数或包含无效值。可查看message以获得更多错误信息。

USER_NOT_FOUND

使用了无效的API KEY或用户不存在。

GROUP_NOT_FOUND

使用了无效的API KEY或用户分组不存在。

PERMISSION_DENIED

经过身份验证的用户无权执行此操作。

UNKNOWN

发生了意外的错误。检查message以获得更多错误信息。

代码示例

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

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

import os
import requests

# Constants
ENDPOINT = "https://api.hyper3d.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())

package main

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

const BaseURI = "https://api.hyper3d.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)
}

{
  "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)

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

import os
import requests

# Constants
ENDPOINT = "https://api.hyper3d.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())

package main

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

const BaseURI = "https://api.hyper3d.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)
}

{
  "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)

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

{
  "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)

export RODIN_API_KEY="your api key"
curl https://api.hyper3d.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

import os
import requests

# Constants
ENDPOINT = "https://api.hyper3d.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())

{
  "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)

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

import os
import requests

# Constants
ENDPOINT = "https://api.hyper3d.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())

{
  "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

export RODIN_API_KEY="your api key"
curl https://api.hyper3d.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

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

上一页Gen-2 Generation 下一页Bang!

最后更新于24天前

这有帮助吗？

hashtagThe all in one API for generating Rodin.

hashtagRodin生成

hashtag价格

hashtag请求

hashtagAuthentication

hashtagBody

hashtag响应

hashtag代码示例

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

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

hashtagMinimal Rodin Generation(Text-to-3D)

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

hashtagMinimal Rodin ControlNet Generation(Bounding Box Condition)

hashtagComprehensive Rodin Regular Generation with All Parameters

The all in one API for generating Rodin.

Rodin生成

价格

请求

Authentication

Body

响应

代码示例

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

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

Minimal Rodin Generation(Text-to-3D)

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

Minimal Rodin ControlNet Generation(Bounding Box Condition)

Comprehensive Rodin Regular Generation with All Parameters