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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.hyper3d.ai/zh_cn/api-specification/rodin-generation-gen2_reset_v.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.