> For the complete documentation index, see [llms.txt](https://developer.hyper3d.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.hyper3d.ai/zh_cn/api-specification/rodin-generation_reset_v.md).
# Gen-1&1.5 Generation
{% openapi src="/files/5w81V2d3ohxMjZNUCiOF" path="/api/v2/rodin" method="post" %}
[tmp.yaml](https://563398440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiMYwiLTHWAzkgBEpY5K%2Fuploads%2Fgit-blob-74b44ac4fa8f9db435ebd9d2d2be7fc11aca2bbd%2Ftmp.yaml?alt=media)
{% endopenapi %}
## Rodin生成
使用此API向我们的服务器提交异步任务。你将从API中获得一个任务UUID，该UUID可用于[ 检查进度 ](/zh_cn/api-specification/check-status_reset_v.md)和[ 下载结果 ](/zh_cn/api-specification/download-results_reset_v.md)。
### 价格
{% hint style="info" %}
**Note**: 参数不会收取任何额外费用，只有模型附加项才会有额外收费。
{% endhint %}
* **Base Cost**: 每次生成消耗 0.5 Credit。
* **Addons**:
* `HighPack`: 每次生成额外消耗 1 Credit。
### 请求
{% hint style="info" %}
**Note**: 所有到这个端点的请求都必须使用`multipart/form-data`发送，以正确处理文件上传以及网格和纹理生成过程所需的其他参数。
{% endhint %}
#### Authentication
此API使用密钥进行身份验证。您需要在所有请求的`Authorization`头中包含一个有效的密钥. 参阅[快速开始](/zh_cn/get-started/readme.md#authentication-for-rodin-api)获取您的账户的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材质。
None: 无材质。 |
| 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`，生成结束后的下载列表中将会额外多一张高质量渲染图像。
{% hint style="info" %}
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`参数的值。
{% endhint %}
{% hint style="info" %}
**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)
```
{% endhint %}
### **响应**
{% hint style="info" %}
对于[response from the Generation API](#response)的`task_uuid`，使用`uuid`字段替代`jobs_uuid`。
{% endhint %}
| 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)
{% tabs %}
{% tab title="Request with cURL" %}
```bash
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
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import os
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = os.getenv("HYPER3D_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())
```
{% endtab %}
{% tab title="Request with Go" %}
```go
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)
}
```
{% endtab %}
{% tab title="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"
}
}
```
{% endtab %}
{% endtabs %}
#### Minimal Rodin Sketch Generation(Image-to-3D)
{% tabs %}
{% tab title="Request with cURL" %}
```bash
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
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import os
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = os.getenv("HYPER3D_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())
```
{% endtab %}
{% tab title="Request with Go" %}
```go
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)
}
```
{% endtab %}
{% tab title="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"
}
}
```
{% endtab %}
{% endtabs %}
#### Minimal Rodin Generation(Text-to-3D)
{% tabs %}
{% tab title="Request with cURL" %}
```bash
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
```
{% endtab %}
{% tab title="Response" %}
{
"error": null,
"message": "Submitted.",
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"jobs": {
"uuids": ["job-uuid-1", "job-uuid-2"],
"subscription_key": "sub-key-1"
}
}
{% endtab %}
{% endtabs %}
#### Minimal Rodin Generation(Image-to-3D with multi-view images)
{% tabs %}
{% tab title="Request with cURL" %}
```bash
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
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import os
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = os.getenv("HYPER3D_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())
```
{% endtab %}
{% tab title="Response" %}
{
"error": null,
"message": "Submitted.",
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"jobs": {
"uuids": ["job-uuid-1", "job-uuid-2"],
"subscription_key": "sub-key-1"
}
}
{% endtab %}
{% endtabs %}
#### Minimal Rodin ControlNet Generation(Bounding Box Condition)
{% tabs %}
{% tab title="Request with cURL" %}
```bash
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
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import os
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = os.getenv("HYPER3D_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())
```
{% endtab %}
{% tab title="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"
}
}
{% endtab %}
{% endtabs %}
#### Comprehensive Rodin Regular Generation with All Parameters
{% tabs %}
{% tab title="Request with cURL" %}
```bash
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
```
{% endtab %}
{% tab title="Response" %}
{
"error": null,
"message": "Submitted.",
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"jobs": {
"uuids": ["job-uuid-1", "job-uuid-2"],
"subscription_key": "sub-key-1"
}
}
{% endtab %}
{% endtabs %}