Gen-2.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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

imagesstring · binaryOptional

promptstringOptional

tierstring · enumOptionalPossible values:

use_original_alphabooleanOptionalDefault: false

seednumberOptional

geometry_file_formatstring · enumOptionalDefault: glbPossible values:

materialstring · enumOptionalDefault: PBRPossible values:

qualitystring · enumOptionalDefault: mediumPossible values:

quality_overridenumberOptional

TAposebooleanOptionalDefault: false

mesh_modestring · enumOptionalDefault: RawPossible values:

preview_renderbooleanOptionalDefault: false

hd_texturebooleanOptionalDefault: false

texture_delightbooleanOptionalDefault: false

texture_modestring · enumOptionalPossible values:

is_microbooleanOptionalDefault: false

geometry_instruct_modestring · enumOptionalDefault: faithfulPossible values:

Responses

201Success

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=Gen-2.5-High" \ 
--file "mesh_mode=Raw" \
...

201Success

{
  "error": "text",
  "message": "text",
  "uuid": "text",
  "jobs": {
    "uuids": [
      "text"
    ],
    "subscription_key": "text"
  }
}

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 of the task and download the result when the task is ready.

Pricing

Note: There are no additional fees for parameters. Only addons incur extra charges.

Addons:
- HighPack: Additional 1 credit per generation.

Request

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.

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

Parameter

Type

Description

images

file/Binary

Images to be used in generation, up to 5 images. For Image-to-3D generation: required (one or more images are needed, maximum 5 images) For Text-to-3D generation: null

prompt

string

A textual prompt to guide the model generation. For Image-to-3D generation: optional (if not provided, an AI-generated prompt based on the provided images will be used) For Text-to-3D generation: required

use_original_alpha

boolean

Default is false. If True, the original transparency channel of the images will be used when processing the image.

seed

number

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.

geometry_file_format

string

Optional. The format of the output geometry file. Possible values are glb, usdz, fbx, obj, and stl. Default is glb.

material

string

Optional. The material type. Possible values are PBR, Shaded and All. Default is PBR. PBR: Physically Based Materials, including base color texture, metallicness texture, normal texture and roughness texture, providing high realism and physically accurate over dynamic lighting. Shaded: Only base color texture with baked lighting, providing stylized visuals. All: Both PBR and Shaded will be delivered. None: Asset without material.

quality

string

Optional. The face count of the generated model. Possible values are: high: 1M faces(Raw)/50k faces(Quad). medium: 500k faces(Raw)/18k faces(Quad). low: 60k faces(Raw)/8k faces(Quad). extra-low: 20k faces(Raw)/4k faces(Quad). Default is medium.

quality_override

number

Optional. Customize poly count for generation, the range of this parameter is different for each tier and mesh_mode. If mesh_mode is Quad, the range of this parameter is 1000 to 200,000. If mesh_mode is Raw and tier is Gen-2.5-High or Gen-2.5-Extreme-High, the range of this parameter is 20,000 to 2,000,000. If mesh_mode is Raw and tier is not Gen-2.5-High or Gen-2.5-Extreme-High, the range of this parameter is 500 to 1,000,000. This parameter is an advanced parameter of quality. When this parameter is invoked, the quality parameter will not take effect.

tier

string

Tier of generation. To use Gen-2.5, please set the 'tier' to following values: Gen-2.5-Extreme-Low: Best for quickly generating simple assets. Gen-2.5-Low: Suitable for clean assets and small hardsurface props. Gen-2.5-Medium:Ideal for moderately complex models that need balanced structure and detail. Gen-2.5-High:Recommended for high-quality assets with richer structural representation and smooth surfaces. Gen-2.5-Extreme-High:Best for assets that require high-frequency detail reproduction.

TAPose

bool

Optional. When generating the human-like model, this parameter control the generation result to T/A Pose. When true, your model will be either T pose or A pose.

bbox_condition

Array of Integer

Optional. This is a controlnet that controls the maxmimum sized of the generated model. This array must contain 3 elements, Width(Y-axis), Height(Z-axis), and Length(X-axis), in this exact fixed sequence (y, z, x).

mesh_mode

string

Optional. It controls the type of faces of generated models, Possible values are Raw and Quad. Default is Raw. The Raw mode generates triangular face models. The Quad mode generates quadrilateral face models.

addons

array of strings

Optional. The default is []. Possible values is HighPack. By selecting HighPack: Generate 4K resolution texture instead of the default 2K. If Quad mode, he number of faces will be ~16 times of the number of faces selected in the quality parameter.

preview_render

bool

Optional. Default is false. If true, an additional high-quality render image will be provided in the download list.

hd_texture

bool

Optional. Default is false. If true, post-processing is applied to refine and enhance the texture. This improves texture quality but may reduce similarity to the original input.

texture_delight

bool

Optional. Default is false. If true, this parameter applies images preprocessing to remove lighting information from textures.

texture_mode

string

Optional. Possible values are legacy, extreme-low, low, medium and high. Higher values invest more thinking effort and produce better results, at the cost of longer generation time.

is_micro

bool

Optional. Default is false. If true, the mirco detail scale. This parameter is only available in Gen-2.5-Extreme-High tier.

geometry_instruct_mode

string

Optional. Default is faithful, possible values are faithful and creative. creative mode is only available in `Gen-2.5-Medium`, `Gen-2.5-High` and `Gen-2.5-Extreme-High` tier.

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.

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)

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.

Response

Use the uuid field instead of the jobs.uuids field for your requests to Check Status and Download Results API endpoints.

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

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.

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

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())

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

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.

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

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())

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

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.

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

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())

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

Text-to-3D Generation

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

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

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

PreviousGen-1&1.5 Generation NextBang!

Last updated 7 days ago

Was this helpful?