> 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-gen2_reset_v.md).

# Gen-2 Generation

{% openapi src="/files/hUxAth70CiEv2PptydV3" path="/api/v2/rodin" method="post" %}
[tmp\_gen2.yaml](https://563398440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiMYwiLTHWAzkgBEpY5K%2Fuploads%2Fgit-blob-1b1889266f089d9cdd86238f28fe566ff6c96e8b%2Ftmp_gen2.yaml?alt=media)
{% endopenapi %}

## Rodin生成

### ***请求时调用参数 'tier=Gen-2' 以使用Gen-2生成模型***

使用此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**

<table data-full-width="true"><thead><tr><th>参数</th><th>类型</th><th>描述</th></tr></thead><tbody><tr><td><strong>tier</strong></td><td>string</td><td><em><strong>将该参数值设置为<code>Gen-2</code>来调用Gen-2生成模型</strong></em>。<br>必须！<br>默认值为<code>Regular</code>。</td></tr><tr><td>images</td><td>file/Binary</td><td>用于图像生成，最多上传5张图片。由于form-data请求将保留图像的顺序，因此将会使用上传列表的第一张图片来生成材质贴图。<br>对于Image-to-3D模式，图片是必须的。可上传一张或多张图片。（最多上传5张图片。）<br>对于Text-to-3D模式，则不需要上传图片。</td></tr><tr><td>prompt</td><td>string</td><td>用于指导模型生成的文本提示。<br>对于Image-to-3D生成模式是可选的。(如果没有提供，将使用基于提供的图像的人工智能生成的提示。)<br>对Text-to-3D模式是必须的。</td></tr><tr><td>use_original_alpha</td><td>boolean</td><td>默认是<code>false</code>. 如果 <code>True</code>, 上传图像的透明度通道将会直接被用于图片处理。</td></tr><tr><td>seed</td><td>number</td><td>可选的。网格生成中用于随机化的种子值，范围从0到65535(包括两者)。如果不提供，种子将随机生成。</td></tr><tr><td>geometry_file_format</td><td>string</td><td>可选的。模型文件的格式。可能的值为<code>glb</code>，<code>usdz</code>，<code>fbx</code>，<code>obj</code>，<code>stl</code>。默认值为<code>glb</code>。</td></tr><tr><td>material</td><td>string</td><td>可选的。材质类型。可能的值为<code>PBR</code>，<code>Shaded</code>和<code>All</code>。默认值为<code>PBR</code>。<br><code>PBR</code>：物理基础材质，包括基础颜色纹理、金属度纹理、法线纹理和粗糙度纹理，提供高真实感并在动态光照下具有物理准确性。<br><code>Shaded</code>：仅包含基础颜色纹理和烘焙光照，提供风格化的视觉效果。<br><code>All</code>：会同时生成<code>PBR</code>和<code>Shaded</code>材质。<br><code>None</code>: 无材质。</td></tr><tr><td>quality</td><td>string</td><td>可选的。控制生成模型的面数。<br>可选值有<code>high</code>, <code>medium</code>, <code>low</code>, 和<code>extra-low</code>.<br>当mesh_mode为<code>Raw</code>时: <code>high</code>: 500k, <code>medium</code>: 150k, <code>low</code>: 20k, <code>extra-low</code>: 2k, 默认值为<code>high</code>。<br>当mesh_mode为<code>Quad</code>时: <code>high</code>: 50k, <code>medium</code>: 18k, <code>low</code>: 8k, <code>extra-low</code>: 4k, 默认值为<code>medium</code>。</td></tr><tr><td>TAPose</td><td>bool</td><td>可选的。控制生成类人模型时，生成结果展现为T/A Pose。<br>当该值为<code>true</code>时，生成的模型将为Tpose或者Apose。</td></tr><tr><td>bbox_condition</td><td>Array of Integer</td><td>可选的。该参数是一个控制生成模型最大生成边界的control net.<br>通常来说，这个数组包含三个元素，分别是宽度（y轴），高度（z轴）和长度（x轴）。</td></tr><tr><td>mesh_mode</td><td>string</td><td>可选的，可选的值有<code>Raw</code>和<code>Quad</code>. 默认值为<code>Quad</code>.<br><code>Raw</code>模式会生成<strong>三角面</strong>模型。<br><code>Quad</code>模式生成<strong>四边面</strong>模型。</td></tr><tr><td>addons</td><td>array of strings</td><td>可选的。生成附加功能。默认为<code>[]</code>。可能的值为<code>HighPack</code>.<br>当选择<code>HighPack</code>选项时：<br>提供4K分辨率的纹理贴图而不是基础的2K分辨率。<br>当mesh_mode为<code>Quad</code>时，还会提供更高面数的模型文件。(约16倍选择quality对应面数。)</td></tr><tr><td>preview_render</td><td>bool</td><td>可选的， 默认为<code>false</code>.<br>如果<code>true</code>，生成结束后的下载列表中将会额外多一张高质量渲染图像。</td></tr><tr><td>hd_texture</td><td>bool</td><td>可选的， 默认为<code>false</code>.<br>如果<code>true</code>，高质量纹理贴图。</td></tr></tbody></table>

{% hint style="info" %}
Rodin 提供了两种生成模式:

* **Image-to-3D**:

  当你上传**一张或多张** `images` 时，将会自动启用图生3D模式。

  * 单一图片: 上传**一张**图片来生成3D模型。
  * 多图片: 将所有上传图片作为同一物体的多视角图片进行3D模型生成。**上传图片的第一张图片将作为贴图生成的参考图**。

  **注意**: Form data 请求体会维持你上传图片的顺序，确保你上传图片的顺序正确。
* **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](/zh_cn/api-specification/rodin-generation_reset_v.md#response)的`task_uuid`，使用`uuid`字段替代`jobs_uuid`。
{% endhint %}

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>error</td><td>enum</td><td>错误信息（如有）。</td></tr><tr><td>message</td><td>string</td><td>成功信息或详细的错误信息。</td></tr><tr><td>uuid</td><td>string</td><td>生成任务的唯一标识符。</td></tr><tr><td>jobs</td><td>object</td><td>一个作业对象，包含作为生成过程一部分执行的各个作业的详细信息。</td></tr><tr><td>jobs.uuids</td><td>array of strings</td><td>子任务的UUIDs。</td></tr><tr><td>jobs.subscription_key</td><td>string</td><td>任务密钥</td></tr></tbody></table>

可能出现的报错信息包括:

<table data-full-width="true"><thead><tr><th>Error</th><th>描述</th></tr></thead><tbody><tr><td>NO_ACTIVE_SUBSCRIPTION</td><td>没有有效订阅或订阅已经过期。</td></tr><tr><td>SUBSCRIPTION_PLAN_TOO_LOW</td><td>当前订阅计划等级过低，需要商业计划以使用API功能。</td></tr><tr><td>INSUFFICIENT_FUND</td><td>用户账户余额不足，无法完成请求的操作。</td></tr><tr><td>INVALID_REQUEST</td><td>请求格式错误、缺少必要参数或包含无效值。可查看<code>message</code>以获得更多错误信息。</td></tr><tr><td>USER_NOT_FOUND</td><td>使用了无效的API KEY或用户不存在。</td></tr><tr><td>GROUP_NOT_FOUND</td><td>使用了无效的API KEY或用户分组不存在。</td></tr><tr><td>PERMISSION_DENIED</td><td>经过身份验证的用户无权执行此操作。</td></tr><tr><td>UNKNOWN</td><td>发生了意外的错误。检查<code>message</code>以获得更多错误信息。</td></tr></tbody></table>

### **代码示例**

#### Minimal Rodin Gen-2 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=Gen-2" 
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')),
    ('tier', (None, 'Gen-2')),
]

# 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
    }

    // Set the tier to Rodin Gen-2
    fieldWriter, err = writer.CreateFormField("tier")
    if err != nil {
        return nil, err
    }

    if _, err = fieldWriter.Write([]byte("Gen-2")); 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 Gen-2 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" \
  -F "tier=Gen-2" 
unset RODIN_API_KEY
```

{% endtab %}

{% tab title="Response" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

#### Minimal Rodin Gen-2 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" \
  -F "tier=Gen-2"
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

# Read the image file
with open(IMAGE_PATH_0, 'rb') as image_file:
    image_data_0 = image_file.read()

with open(IMAGE_PATH_1, 'rb') as image_file:
    image_data_1 = image_file.read()

# Prepare the multipart form data
files = [
    ('images', (os.path.basename(IMAGE_PATH_0), image_data_0, 'image/jpeg')),
    ('images', (os.path.basename(IMAGE_PATH_1), image_data_1, 'image/jpeg')),
    ('tier', (None, 'Gen-2')),
]

# 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" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

#### Comprehensive Rodin Gen-2 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 "tier=Gen-2" \
  -F "prompt=A 3D model of a futuristic robot" \
  -F "mesh_mode=Raw" \
  -F "seed=42" \
  -F "geometry_file_format=fbx" \
  -F "material=PBR" \
  -F "quality_override=500000" \
unset RODIN_API_KEY
```

{% endtab %}

{% tab title="Response" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}
</code></pre>

{% endtab %}
{% endtabs %}