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

bearer

Body

multipart/form-data

imagesstring · binaryRequired

promptstringOptional

use_original_alphabooleanOptionalDefault: false

condition_modestring · enumOptionalDefault: concatPossible values:

seednumberOptional

geometry_file_formatstring · enumOptionalDefault: glbPossible values:

materialstring · enumOptionalDefault: PBRPossible values:

qualitystring · enumOptionalDefault: mediumPossible values:

quality_overridenumberOptional

tierstring · enumOptionalPossible values:

TAPosebooleanOptionalDefault: false

mesh_modestring · enumOptionalDefault: QuadPossible values:

mesh_simplifybooleanOptionalDefault: true

mesh_smoothbooleanOptionalDefault: true

preview_renderbooleanOptionalDefault: false

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

Post requests with 'tier=Gen-2' to invoke Gen-2 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.

• 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
tier	string	Set the value to Gen-2 to invoke Gen-2 generaion. Required. Tier of generation. The default value is Regular.
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
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.
quality	string	Optional. The generation quality. Possible values are high, medium, low, and extra-low. For Raw: high: 500k, medium: 150k, low: 20k, extra-low: 2k, Default is high. For Quad: high: 50k, medium: 18k, low: 8k, extra-low: 4k, Default is medium.
quality_override	number	Optional. Customize poly count for generation, providing more accurate control over mesh face count. When mesh_mode = Raw: Range from 500 to 1,000,000. Default is 500,000. When mesh_mode = Quad: Range from 1,000 to 200,000. Default is 18,000. Recommend 150,000+ faces for Gen-2. This parameter is an advanced parameter of quality. When this parameter is invoked, the quality parameter will not take effect.
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, addons will be fixed to [].
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, the 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.

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.

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 Gen-2 Generation(Image-to-3D)

Request with cURL

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

Request with Python 3

import os
import requests

# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = "your api key"  # Replace with your actual 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())

Request with 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)
}

Response

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

Minimal Rodin Gen-2 Generation(Text-to-3D)

Request with cURL

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

Response

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

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

Request with cURL

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

Request with Python 3

import os
import requests

# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = "your api key"  # Replace with your actual 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())

Response

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

Comprehensive Rodin Gen-2 Generation with All Parameters

Request with cURL

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 "mesh_simplify=True" \
  -F "seed=42" \
  -F "geometry_file_format=fbx" \
  -F "material=PBR" \
  -F "quality_override=500000" \
unset RODIN_API_KEY

Response

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