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提供两种生成模式: 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)

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!

最后更新于2个月前

这有帮助吗？