Rodin Generation

The all in one API for generating Rodin.

post

This API will generate a mesh and textures for the given images and prompt. This API provide two tiers of generation, Sketch and Regular. Sketch is optimized for generation speed, and is recommended for fast prototyping. Regular is optimized for quality, and is recommended for production.

Authorizations
Body
imagesstring · binaryRequired
promptstringOptional
condition_modestring · enumOptionalDefault: concatPossible values:
seednumberOptional
geometry_file_formatstring · enumOptionalDefault: glbPossible values:
materialstring · enumOptionalDefault: PBRPossible values:
qualitystring · enumOptionalDefault: mediumPossible values:
tierstring · enumOptionalPossible values:
TAPosebooleanOptionalDefault: false
bbox_conditionarrayOptionalDefault: []
mesh_modestring · enumOptionalDefault: QuadPossible values:
mesh_simplifybooleanOptionalDefault: true
mesh_smoothbooleanOptionalDefault: true
Responses
201Success
application/json
post
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=Regular" \ 
...
201Success
{
  "error": "text",
  "message": "text",
  "uuid": "text",
  "jobs": {
    "uuids": [
      "text"
    ],
    "subscription_key": "text"
  }
}

Rodin Generation

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

  • Base Cost: 0.5 credit per generation for either Sketch and Regular tier.

  • 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. Refer to the Quickstart section for how to generate an API key for your account.

Authorization: Bearer RODIN_API_KEY

Body

Parameter
Type
Description

images

file/Binary

Images to be used in generation, up to 5 images. As the form data request will preserve the order of the images, the first image will be the image for material generation. 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

condition_mode

string

Useful only for multi-images 3D generation. This is an optional parameter that chooses the mode of the multi-image geneartion. Possible values are fuse and concat. Default is concat. For fuse mode, if you are uploading images of multiple objects, fuse mode will extract and fuse all the features of all the objects from the images for generation. One or more images are required.

For concat mode, if you are uploading images of a single object, concat mode will inform the Rodin model to expect these images to be multi-view images of a single object. One or more images are required (you can upload multi-view images in any order, regardless of the order of view.)

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. For Rodin Sketch, the value will fixed to glb.

material

string

Optional. The material type. Possible values are PBR and Shaded. Default is PBR. For Rodin Sketch, the value will fixed to PBR.

quality

string

Optional. The generation quality. Possible values are high(50k faces), medium(18k faces), low(8k faces), and extra-low(4k faces). Default is medium. For Rodin Sketch, the value will fixed to medium.

tier

string

Optional. Tier of generation. The default value is Regular. Sketch: Fast generation with basic details, suitable for initial concepts. Regular: Balanced quality and speed, ideal for general use. Detail: Enhanced details compared to Regular, recommended for intricate results (longer processing time). Smooth: Clearer and sharper output than Regular, with slightly longer processing time.

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 Quad. The Raw mode generates triangular face models. The Quad mode generates quadrilateral face models. When its value is Raw, quality will be fixed to medium, and addons will be fixed to [].

mesh_simplify

bool

Optional. Default is true. If true, The generated models will be simplified. This parameter takes effect when the mesh_mode is set to Raw.

mesh_smooth

bool

Optional. Default is true. If true, The generated models will be smoothed. Similar to Rodin Gen-1. This parameter takes effect when the mesh_mode is set to Quad.

addons

array of strings

Optional. The default is []. Possible values is HighPack. By selecting HighPack, it will generate 4K resolution texture instead of the default 2K, and the number of faces will be ~16 times of the number of faces selected in the quality parameter.

Rodin provides two generation modes: Text-to-3D and Image-to-3D. Image-to-3D: When you upload Image files, Rodin will automatically select Image-to-3D mode and you can upload one or more image files. When Multiple images are uploaded,

  • fuse mode will combine all the features of the image to generate.

  • And concat mode expects these images to be multi-view images of a single model. As the form data request will preserve the order of the images, the first image will be the image for material generation.

Text-to-3D: When you have not uploaded any image files, you must upload the "prompt" parameter and Rodin will change to 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: An array that specifies the dimensions and scaling factor of the bounding box.

      • Elements:

        1. Width (Y-axis):100 units.

        2. Height (Z-axis):100 units.

        3. Length (X-axis):100 uints.

      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)                        

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

string

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.

Examples

Minimal Rodin Regular Generation(Image-to-3D)

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

Minimal Rodin Sketch Generation(Image-to-3D)

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

Minimal Rodin Generation(Text-to-3D)

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

Minimal Rodin Generation(Image-to-3D with multi-view images)

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

Minimal Rodin ControlNet Generation(Bounding Box Condition)

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

Comprehensive Rodin Regular Generation with All Parameters

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

Last updated

Was this helpful?