# Gen-1&1.5 Generation {% openapi src="" path="/api/v2/rodin" method="post" %} [tmp.yaml](https://3170127470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fve7H9sNOF32Exg6OAhKo%2Fuploads%2Fgit-blob-37a7ab25a5bd5ce71dae46dea38154ce84cb4ffb%2Ftmp.yaml?alt=media) {% endopenapi %} ## 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 ](https://developer.hyper3d.ai/api-specification/check-status_reset_v)of the the task and [download the result ](https://developer.hyper3d.ai/api-specification/download-results_reset_v)when the task is ready. ### Pricing {% hint style="info" %} **Note**: There are no additional fees for parameters. Only addons incur extra charges. {% endhint %} * **Base Cost**: 0.5 credit per generation. * **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**

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
use_original_alpha	boolean	Default is `false`. If `True`, the original transparency channel of the images will be used when processing the image.
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`.
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 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`.
quality_override	number	Optional. Customize poly count for generation, ranging from 2000 to 200000, providing more accurate control over mesh face count. This parameter is an advanced parameter of `quality`. When this parameter is invoked, the `quality` parameter will not take effect. For Rodin Sketch, this parameter will not take effect and the mesh quality will use the default value of `quality`.
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 `[]`. For Rodin Sketch tier, only triangular face could be generated.
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 `false`. 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`: 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.

{% hint style="info" %} Rodin 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, you must specify the processing mode: `fuse` mode: Combines features from all uploaded images to generate a single 3D model. `concat` mode: Treats the images 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, especially when using `concat` mode. * **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**: 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) ``` {% endhint %} ### **Response** {% hint style="info" %} Use the `uuid` field instead of the `jobs.uuids` field for your requests to [Check Status ](https://developer.hyper3d.ai/api-specification/check-status_reset_v)and [Download Results](https://developer.hyper3d.ai/api-specification/download-results_reset_v) 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	Bussiness subscription is required to use Rodin Gen-1/1.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.

### **Examples** #### Minimal Rodin Regular 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" 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 # Prepare the multipart form data files = [ ('images', open(IMAGE_PATH, 'rb')), ] # 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 } // 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 Sketch 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=Sketch" 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 # Set the tier to Rodin Sketch files = { 'images': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg'), 'tier':(None, 'Sketch'), } # 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 } // Set the tier to Rodin Sketch fieldWriter, err = writer.CreateFormField("tier") if err != nil { return nil, err } if _, err = fieldWriter.Write([]byte("Sketch")); 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 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" \ unset RODIN_API_KEY ``` {% endtab %} {% tab title="Response" %}

{
  "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 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" 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 # Prepare the multipart form data files = [ ('images', open(IMAGE_PATH_0, 'rb')), ('images', open(IMAGE_PATH_1, 'rb')), ] # 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" %}

{
  "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 ControlNet Generation(Bounding Box Condition) {% 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 "bbox_condition=[100,100,100]" -F "prompt=A sofa." 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 images data # Prepare the Bounding Box data files = { 'images': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg'), 'bbox_condition':(None, "[100, 100, 100]"), } # 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" %}

{
  "error": null,
  "message": "Submitted. Please check progress via /api/v2/status and get download link via /api/v2/download",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

{% endtab %} {% endtabs %} #### Comprehensive Rodin Regular 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 "prompt=A 3D model of a futuristic robot" \ -F "seed=42" \ -F "geometry_file_format=fbx" \ -F "material=PBR" \ -F "quality=high" \ -F "tier=Regular" \ -F "addons=HighPack" unset RODIN_API_KEY ``` {% endtab %} {% tab title="Response" %}

{
  "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-generation_reset_v.md?ask= ``` 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.