# Gen-2.5 Generation

{% openapi src="/files/dJuXSNNuPCF6sSgzt2T2" path="/api/v2/rodin" method="post" %}
[tmp\_rodin\_gen2\_5.yaml](https://3170127470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fve7H9sNOF32Exg6OAhKo%2Fuploads%2Fgit-blob-0d31e2149d0e62ea819b12f4d8beac0117844e31%2Ftmp_rodin_gen2_5.yaml?alt=media)
{% endopenapi %}

## Rodin Generation - Gen-2.5

### Use Gen-2.5 Generation with following Gen-2.5 tiers:

| Tier                 | Description                                                                                    | Credits Cost |
| -------------------- | ---------------------------------------------------------------------------------------------- | ------------ |
| Gen-2.5-Extreme-Low  | Best for quickly generating simple assets.                                                     | 0.5 credit   |
| Gen-2.5-Low          | Suitable for clean assets and small hardsurface props.                                         | 0.5 credit   |
| Gen-2.5-Medium       | Ideal for moderately complex models that need balanced structure and detail.                   | 0.5 credits  |
| Gen-2.5-High         | Recommended for high-quality assets with richer structural representation and smooth surfaces. | 0.5 credits  |
| Gen-2.5-Extreme-High | Best for assets that require high-frequency detail reproduction.                               | 1.0 credits  |

Use this API to submit an asynchronous task to our server. You will get a task UUID from the API which can be used to [check the status](/api-specification/check-status_reset_v.md) of the task and [download the result](/api-specification/download-results_reset_v.md) when the task is ready.

### Pricing

{% hint style="info" %}
**Note**: There are no additional fees for parameters. Only addons incur extra charges.
{% endhint %}

* **Addons**:
  * `HighPack`: Additional 1 credit per generation.

### Request

{% hint style="info" %}
**Note**: All requests to this endpoint must be sent using `multipart/form-data` to properly handle the file uploads and additional parameters required for the mesh and texture generation process.
{% endhint %}

#### Authentication

This API uses bearer key for authentication. You need to include a valid token in the `Authorization` header for all requests.

```
Authorization: Bearer RODIN_API_KEY
```

#### **Body**

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>images</td><td>file/Binary</td><td>Images to be used in generation, up to 5 images.<br>For Image-to-3D generation: required (one or more images are needed, maximum 5 images)<br>For Text-to-3D generation: null</td></tr><tr><td>prompt</td><td>string</td><td>A textual prompt to guide the model generation.<br>For Image-to-3D generation: optional (if not provided, an AI-generated prompt based on the provided images will be used)<br>For Text-to-3D generation: required</td></tr><tr><td>use_original_alpha</td><td>boolean</td><td>Default is <code>false</code>. If <code>True</code>, the original transparency channel of the images will be used when processing the image.</td></tr><tr><td>seed</td><td>number</td><td>Optional. A seed value for randomization in the mesh generation, ranging from 0 to 65535 (both inclusive). If not provided, the seed will be randomly generated.</td></tr><tr><td>geometry_file_format</td><td>string</td><td>Optional. The format of the output geometry file. Possible values are <code>glb</code>, <code>usdz</code>, <code>fbx</code>, <code>obj</code>, and <code>stl</code>. Default is <code>glb</code>.</td></tr><tr><td>material</td><td>string</td><td>Optional. The material type. Possible values are <code>PBR</code>, <code>Shaded</code> and <code>All</code>. Default is <code>PBR</code>.<br><code>PBR</code>: Physically Based Materials, including base color texture, metallicness texture, normal texture and roughness texture, providing high realism and physically accurate over dynamic lighting.<br><code>Shaded</code>: Only base color texture with baked lighting, providing stylized visuals.<br><code>All</code>: Both <code>PBR</code> and <code>Shaded</code> will be delivered.<br><code>None</code>: Asset without material.</td></tr><tr><td>quality</td><td>string</td><td>Optional. The face count of the generated model.<br>Possible values are:<br><code>high</code>: 1M faces(<code>Raw</code>)/50k faces(<code>Quad</code>).<br><code>medium</code>: 500k faces(<code>Raw</code>)/18k faces(<code>Quad</code>).<br><code>low</code>: 60k faces(<code>Raw</code>)/8k faces(<code>Quad</code>).<br><code>extra-low</code>: 20k faces(<code>Raw</code>)/4k faces(<code>Quad</code>).<br>Default is <code>medium</code>.</td></tr><tr><td>quality_override</td><td>number</td><td>Optional. Customize poly count for generation, the range of this parameter is different for each tier and mesh_mode.<br>If mesh_mode is <code>Quad</code>, the range of this parameter is 1000 to 200,000.<br>If mesh_mode is <code>Raw</code> and tier is <code>Gen-2.5-High</code> or <code>Gen-2.5-Extreme-High</code>, the range of this parameter is 20,000 to 2,000,000.<br>If mesh_mode is <code>Raw</code> and tier is <strong>not</strong> <code>Gen-2.5-High</code> or <code>Gen-2.5-Extreme-High</code>, the range of this parameter is 500 to 1,000,000.<br>This parameter is an advanced parameter of <code>quality</code>. When this parameter is invoked, the <code>quality</code> parameter will not take effect.</td></tr><tr><td>tier</td><td>string</td><td>Tier of generation. To use Gen-2.5, please set the 'tier' to following values:<br><code>Gen-2.5-Extreme-Low</code>: Best for quickly generating simple assets.<br><code>Gen-2.5-Low</code>: Suitable for clean assets and small hardsurface props.<br><code>Gen-2.5-Medium</code>:Ideal for moderately complex models that need balanced structure and detail.<br><code>Gen-2.5-High</code>:Recommended for high-quality assets with richer structural representation and smooth surfaces.<br><code>Gen-2.5-Extreme-High</code>:Best for assets that require high-frequency detail reproduction.</td></tr><tr><td>TAPose</td><td>bool</td><td>Optional. When generating the human-like model, this parameter control the generation result to T/A Pose.<br>When <code>true</code>, your model will be either T pose or A pose.</td></tr><tr><td>bbox_condition</td><td>Array of Integer</td><td>Optional. This is a controlnet that controls the maxmimum sized of the generated model.<br>This array must contain 3 elements, Width(Y-axis), Height(Z-axis), and Length(X-axis), in this exact fixed sequence (y, z, x).</td></tr><tr><td>mesh_mode</td><td>string</td><td>Optional. It controls the type of faces of generated models, Possible values are <code>Raw</code> and <code>Quad</code>. Default is <code>Raw</code>.<br>The <code>Raw</code> mode generates <strong>triangular face</strong> models.<br>The <code>Quad</code> mode generates <strong>quadrilateral face</strong> models.</td></tr><tr><td>addons</td><td>array of strings</td><td>Optional. The default is <code>[]</code>. Possible values is <code>HighPack</code>.<br>By selecting <code>HighPack</code>:<br>Generate 4K resolution texture instead of the default 2K.<br>If <code>Quad</code> mode, he number of faces will be <strong>~16 times</strong> of the number of faces selected in the <code>quality</code> parameter.</td></tr><tr><td>preview_render</td><td>bool</td><td>Optional. Default is <code>false</code>.<br>If <code>true</code>, an additional high-quality render image will be provided in the download list.</td></tr><tr><td>hd_texture</td><td>bool</td><td>Optional. Default is <code>false</code>.<br>If <code>true</code>, post-processing is applied to refine and enhance the texture. This improves texture quality but may reduce similarity to the original input.</td></tr><tr><td>texture_delight</td><td>bool</td><td>Optional. Default is <code>false</code>.<br>If <code>true</code>, this parameter applies images preprocessing to remove lighting information from textures.</td></tr><tr><td>texture_mode</td><td>string</td><td>Optional. Possible values are <code>legacy</code>, <code>extreme-low</code>, <code>low</code>, <code>medium</code> and <code>high</code>.<br>Higher values invest more thinking effort and produce better results, at the cost of longer generation time.</td></tr><tr><td>is_micro</td><td>bool</td><td>Optional. Default is <code>false</code>.<br>If <code>true</code>, the mirco detail scale. This parameter is only available in Gen-2.5-Extreme-High tier.</td></tr><tr><td>is_symmetric</td><td>bool</td><td>Optional. Default is <code>false</code>.<br>If <code>true</code>, this parameter will determine whether the generated model is symmetric.</td></tr><tr><td>geometry_instruct_mode</td><td>string</td><td>Optional. Default is <code>faithful</code>, possible values are <code>faithful</code> and <code>creative</code>.</td></tr></tbody></table>

{% hint style="info" %}
Rodin Gen-2.5 provides two generation modes:

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

  This mode is automatically selected when you upload one or more `images` files.

  * Single Image: Upload **one** image file to generate a 3D model.
  * Multiple Images: When uploading multiple images, they are automatically treated as multi-view captures of a single object. **The first image in the upload order will be used for material generation**.

  **Important Note**: Form data requests preserve the order of uploaded images. Ensure your images are in the correct sequence for optimal multi-view processing.
* **Text-to-3D**:

  This mode is automatically selected when you **do not** upload any image files.

  * Required Parameter:
    * `prompt`: You must provide a text description to guide the 3D model generation.
  * Important: **No image files** should be uploaded when using Text-to-3D mode.
    {% endhint %}

{% hint style="info" %}
**ControlNet**: ControlNet enhances model customization by providing finer control over the generated outputs. It adds several parameters on top of the original request, allowing users to manipulate aspects such as proportions, shapes, and structures of 3D models.

ControlNet introduces the following main parameters to provide advanced control over the model generation process:

* **BoundingBox ControlNet**: The BoundingBox ControlNet allows users to define the proportions of the generated model by specifying the length, width, and height through a draggable bounding box. This is particularly useful when you want the generated object to fit within specific dimensions or adhere to certain spatial constraints.
  * Example Representation:

    ```
    {
    "bbox_condition": "[100, 100, 100]"
    }
    ```
  * **bbox\_condition**: A string representing an array that specifies the dimensions of the bounding box.

    * Elements:
      1. Width (Y-axis): `100` units.
      2. Height (Z-axis): `100` units.
      3. Length (X-axis): `100` units.

    By setting the `bbox_condition`, you're instructing the model to generate an object that fits within a box of the specified dimensions.
  * **Bounding Box Axis**:

    ```
          World               

        +z(Height)                                                    
        |                                                            
        |                                                        
        |______+y(Width)        
        /                  
       /                      
      /                          
      +x(Length)                        
    ```

{% endhint %}

{% hint style="info" %}
**Creative Mode**: The Creative mode (`geometry_instruct_mode=creative`) enhances generative robustness while ensuring output consistency. When the `Creative` option is enabled, it activates this mode, allowing for more flexible and creative generation while maintaining quality and consistency across outputs. This feature is available for Gen-2.5-Medium and Gen-2.5-High tiers.
{% endhint %}

### **Response**

{% hint style="info" %}
Use the `uuid` field instead of the `jobs.uuids` field for your requests to [Check Status](https://github.com/Deemos-Technology/docs/blob/main/developer-apis/api-specification/check-status.md) and [Download Results](https://github.com/Deemos-Technology/docs/blob/main/developer-apis/api-specification/download-results.md) API endpoints.
{% endhint %}

| Property               | Type             | Description                                                                                     |
| ---------------------- | ---------------- | ----------------------------------------------------------------------------------------------- |
| error                  | enum             | Error message, if any.                                                                          |
| message                | string           | Success message or detailed error information.                                                  |
| uuid                   | string           | Unique identifier for the generated task.                                                       |
| jobs                   | object           | A job object, containing details of individual jobs executed as part of the generation process. |
| jobs.uuids             | array of strings | UUIDs of the sub-jobs.                                                                          |
| jobs.subscription\_key | string           | Subscription key associated with these jobs.                                                    |

Possible Errors include:

| Error                        | Description                                                                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| NO\_ACTIVE\_SUBSCRIPTION     | Does not have an active subscription or the subscription of your account already expired.                                      |
| SUBSCRIPTION\_PLAN\_TOO\_LOW | Business subscription is required to use Rodin Gen-2.5 API.                                                                    |
| INSUFFICIENT\_FUND           | The user's account balance is insufficient to complete the requested operation.                                                |
| INVALID\_REQUEST             | The request is malformed, missing required parameters, or contains invalid values. Check `message` for additional information. |
| USER\_NOT\_FOUND             | API KEY invalid or user not exist.                                                                                             |
| GROUP\_NOT\_FOUND            | API KEY invalid or group not exist.                                                                                            |
| PERMISSION\_DENIED           | The authenticated user does not have permission to perform this action.                                                        |
| UNKNOWN                      | An unexpected error occurred. Check `message` for additional information.                                                      |

### **Generation Modes**

Rodin Gen-2.5 offers three distinct generation modes, each optimized for different use cases:

| Mode             | Tier Options                        | Mesh Faces Range   | Key Features                              | Use Case                                |
| ---------------- | ----------------------------------- | ------------------ | ----------------------------------------- | --------------------------------------- |
| **Regular**      | Gen-2.5-Low/Medium/High             | 1,000 - 1,000,000  | Balanced quality and performance          | Balanced quality and performance        |
| **Fast**         | Gen-2.5-Extreme-Low/Low/Medium/High | 1,000 - 20,000     | Fast generation, limited formats          | Rapid prototyping, low-res applications |
| **Extreme-High** | Gen-2.5-Extreme-High                | 20,000 - 2,000,000 | Ultra-high mesh quality, is\_micro option | Production-ready, high-fidelity outputs |

### **Examples**

#### 1. Regular Mode (Balanced Quality)

The Rodin Gen-2.5 Regular mode provides balanced quality and performance, suitable for most use cases. It supports Creative mode and various mesh options.

{% 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.5-Medium" \
  -F "mesh_mode=Raw" \
  -F "quality_override=500000" \
  -F "texture_mode=high" \
  -F "geometry_instruct_mode=creative"
unset RODIN_API_KEY
```

{% endtab %}

{% tab title="Request with Python 3" %}

```python
import os
import requests

ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = os.getenv("HYPER3D_API_KEY")
IMAGE_PATH = "/path/to/your/image.jpg"

with open(IMAGE_PATH, 'rb') as image_file:
    image_data = image_file.read()

files = [
    ('images', (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg')),
    ('tier', (None, 'Gen-2.5-Medium')),
    ('mesh_mode', (None, 'Raw')),
    ('quality_override', (None, '500000')),
    ('texture_mode', (None, 'high')),
    ('geometry_instruct_mode', (None, 'creative')),
]

headers = {
    'Authorization': f'Bearer {API_KEY}',
}

response = requests.post(ENDPOINT, files=files, headers=headers)
print(response.json())
```

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

#### 2. Fast Mode (Rapid Prototyping)

The Rodin Gen-2.5 Fast mode is optimized for speed, with lower mesh face limits and reduced feature set. Ideal for quick iterations and low-resolution applications.

{% 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.5-Low" \
  -F "mesh_mode=Raw" \
  -F "geometry_file_format=glb" \
  -F "material=Shaded" \
  -F "quality_override=20000" \
  -F "texture_mode=low"
unset RODIN_API_KEY
```

{% endtab %}

{% tab title="Request with Python 3" %}

```python
import os
import requests

ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = os.getenv("HYPER3D_API_KEY")
IMAGE_PATH = "/path/to/your/image.jpg"

with open(IMAGE_PATH, 'rb') as image_file:
    image_data = image_file.read()

files = [
    ('images', (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg')),
    ('tier', (None, 'Gen-2.5-Low')),
    ('geometry_file_format', (None, 'glb')),
    ('material', (None, 'Shaded')),
    ('mesh_mode', (None, 'Raw')),
    ('quality_override', (None, '20000')),
    ('texture_mode', (None, 'low')),
]

headers = {
    'Authorization': f'Bearer {API_KEY}',
}

response = requests.post(ENDPOINT, files=files, headers=headers)
print(response.json())
```

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

#### 3. Extreme-High Mode (Ultra High Quality)

The Extreme-High mode delivers maximum mesh quality with up to 2 million faces. Ideal for production-ready assets requiring highest fidelity.

{% 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.5-Extreme-High" \
  -F "mesh_mode=Raw" \
  -F "quality_override=2000000" \
  -F "material=PBR" \
  -F "texture_mode=high" \
  -F "is_micro=true" \
  -F "geometry_instruct_mode=creative" \
  -F "bbox_condition=[50,80,50]"
unset RODIN_API_KEY
```

{% endtab %}

{% tab title="Request with Python 3" %}

```python
import os
import requests

ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = os.getenv("HYPER3D_API_KEY")
IMAGE_PATH = "/path/to/your/image.jpg"

with open(IMAGE_PATH, 'rb') as image_file:
    image_data = image_file.read()

files = [
    ('images', (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg')),
    ('tier', (None, 'Gen-2.5-Extreme-High')),
    ('mesh_mode', (None, 'Raw')),
    ('quality_override', (None, '2000000')),
    ('material', (None, 'PBR')),
    ('texture_mode', (None, 'high')),
    ('is_micro', (None, 'true')),
    ('geometry_instruct_mode', (None, 'creative')),
    ('bbox_condition', (None, '[50,80,50]')),
]

headers = {
    'Authorization': f'Bearer {API_KEY}',
}

response = requests.post(ENDPOINT, files=files, headers=headers)
print(response.json())
```

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

#### Text-to-3D Generation

Text-to-3D generation is available across all modes by omitting the `images` parameter and providing a `prompt`.

{% 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 fantasy dragon with scales and wings" \
  -F "tier=Gen-2.5-High" \
  -F "mesh_mode=Raw" \
  -F "material=PBR" \
  -F "texture_mode=high" \
  -F "TApose=true"
unset RODIN_API_KEY
```

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


---

# 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/api-specification/rodin-gen2.5.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.