# Introduction
Learn more about the Hyper3D API's capabilities and common use cases.
{% hint style="info" %}
Welcome to the documentation for Hyper3D!
Have feedback about our docs? We'd love to hear from you. Please share your thoughts in our [Discord community](https://discord.com/invite/AhYWCT8WNH).
{% endhint %}
Rodin and ChatAvatar by DeemosTech are advanced 3D asset generators. ChatAvatar is production-ready, creating hyper-realistic 3D facial assets with PBR textures from text or images. Rodin, nearing production readiness, generates realistic 3D models from text or images. Both tools use proprietary diffusion models and a Production-Ready Assets dataset, producing CG-friendly assets for Unity, Unreal Engine, and Maya.
# Get started with Rodin
{% hint style="info" %}
**Note:** You must have a Business subscription to request this API. If you have not yet subscribed, [go here to subscribe](https://hyperhuman.top/subscribe?utm_source=docs\&utm_medium=none\&utm_campaign=dev-docs-subscribe\&utm_id=dev-docs-outlink).
{% endhint %}
### Authentication for Rodin API
Rodin's API uses API keys to authenticate requests. To access Rodin services programmatically, you need to generate an API key. Here’s how to authenticate and use the API keys securely.
#### **Generating an API Key**
1. **Navigate to the API Key Management Page**
* Log into your Rodin account and go to the API Key Management section.
* Click on the "+Create new API Keys" button to generate a new key.
2. **Store Your API Key Securely**
* Once created, the API key will be displayed **only** **once**. Ensure you copy and store it securely. If you lose the key, you will need to generate a new one.
3. **Revoke Keys When Necessary**
* You can manage your existing API keys and revoke any that are no longer needed directly from the API Key Management page.
#### **Using the API Key for Authentication**
For every API request, include the API key in the Authorization HTTP header. Here’s an example of how to structure your request:
```http
Authorization: Bearer YOUR_RODIN_API_KEY
```
Replace `YOUR_RODIN_API_KEY` with the actual API key you generated.
### Making requests
Once you’ve generated your API key, you can trigger your first request to generate high-quality 3D assets using the example code provided below.
{% tabs %}
{% tab title="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="Python 3" %}
{% code fullWidth="false" %}
```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
files = [
('images', (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg')),
]
# 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())
```
{% endcode %}
{% endtab %}
{% tab title="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 %}
{% endtabs %}
#### Response
When you send a POST request to the Rodin API, the server returns a JSON response. Here is the structure of the response and an explanation of its components.
**Example of a Successful Response**
```json
{
"error": null,
"message": "Submitted.",
"uuid": "example-task-uuid",
"jobs": {
"uuids": ["job-uuid-1", "job-uuid-2"],
"subscription_key": "example-subscription-key"
}
}
```
**Fields in the Response**
* **error**: This field will be `null` if the request is successful. If there is an error, it will contain a string describing the error.
* **message**: A string message indicating the status of the request. For successful submissions, this will typically be "Submitted."
* **uuid**: A unique identifier for the task spawned by your request. This `uuid` is used to track the overall task.
* **jobs**: An array of job objects. Each job object represents a step in the task and includes:
* **uuids**: An array of unique identifiers for the individual jobs. Each job corresponds to a specific process involved in the task, such as model generation or texture generation.
* **subscription\_key**: A key used to query the status of each job. This key allows you to track the progress and completion of the jobs.
### Check Status and Download Results
The Generation APIs are time and resource consuming, so we designed them to be asynchronous. This means that you submit a task without getting the result immediately.
With the [Progress Check](https://github.com/Deemos-Technology/docs/blob/main/developer-apis/api-specification/check-status.md) and [Download](https://github.com/Deemos-Technology/docs/blob/main/developer-apis/api-specification/download-results.md) API endpoint, you can check the status of your submitted job and download results from the task. **You are advised to use the Progress Check API to ensure if your task is ready before downloading as we demostrated in the** [**Minimal Example**](/get-started/minimal-example) **to avoid unexpected results.**
As a quick and dirty example in this quick start, we will show you how to get a list of URL to download your results, assuming your task is ready for download.
{% tabs %}
{% tab title="cURL" %}
```bash
export RODIN_API_KEY="your api key"
curl -X 'POST' \
'https://api.hyper3d.com/api/v2/download' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"task_uuid": "{REPLACE TASK UUID YOU GOT FROM LAST STEP}"
}'
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Python 3" %}
```python
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/download"
API_KEY = os.getenv("HYPER3D_API_KEY")
TASK_UUID = "your-task-uuid" # Replace with your actual task UUID
# Prepare the headers
headers = {
'accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': f'Bearer {API_KEY}',
}
# Prepare the JSON payload
data = {
"task_uuid": TASK_UUID
}
# Make the POST request
response = requests.post(ENDPOINT, headers=headers, json=data)
# Parse and return the JSON response
print(response.json())
```
{% endtab %}
{% endtabs %}
You will got an JSON response like the following
```json
{
"list": [
{
"url": "https://example.com/",
"name": "test-file"
}
]
}
```
This is an array of files with a **`url`** to download it from and a human-friendly **`name`** of the file. You can download them with your browser or with a script programmingly. The following Bash script parses the return with `jq` and download them with subsequent calls to `curl`.
```bash
export RODIN_API_KEY="your api key"
curl -X 'POST' \
'https://api.hyper3d.com/api/v2/download' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"task_uuid": "{REPLACE TASK UUID YOU GOT FROM LAST STEP}"
}' | \
jq -r '.list[] | "\(.url) \(.name)"' | \
while read url name; do
curl -o "$name" "$url"
done
unset RODIN_API_KEY
```
***
### Next steps
After successfully submitting a task to the Rodin API, here are some recommended next steps to further explore Rodin's capabilities:
1. **Explore Adjustable Parameters**
Check our [Rodin API request specs](https://github.com/Deemos-Technology/docs/blob/main/developer-apis/api-specification/rodin-generation.md) for more adjustable parameters for 3D asset generation. Fine-tune your requests to achieve the desired output with various customizable options.
2. **Explore Other Rodin Generation Models**\
Explore our other [available Rodin generation models](https://github.com/Deemos-Technology/docs/blob/main/developer-apis/api-specification/overview.md) to find the best fit for your needs. Since the default tier is Rodin Sketch, consider looking into other models that might offer additional features or better suit your project requirements
3. **Track Progress**
Use our [Status API ](https://github.com/Deemos-Technology/docs/blob/main/developer-apis/api-specification/check-status.md)to track the status of your 3D asset generation. Monitor each job and ensure everything is progressing as expected.
4. **Retrieve Generated Assets**
Once the 3D asset generation is complete, query our [Download API ](https://github.com/Deemos-Technology/docs/blob/main/developer-apis/api-specification/download-results.md)to package and download the generated assets. Ensure you have all necessary files for your project.
5. **Stay Updated**
Follow us on [Twitter/X](https://x.com/deemostech?lang=en), [Instagram](https://www.instagram.com/deemostechnologies), and [YouTube](https://www.youtube.com/@DeemosTech) for the latest updates on Rodin Gen-1 and ChatAvatar.
# Minimal Example
## Minimal Gen-2 Example
{% hint style="warning" %}
This script is for demostration purpose only. It lacks some cirtical elements for a production-ready script like error handling.
{% endhint %}
```python
import time
import os
import requests
# Define the base URL, the API key and Paths
base_url = "https://api.hyper3d.com/api/v2"
api_key = "your api key"
image_path = "/your/image/path/robot.jpg"
result_path = "/your/result/path"
# Define the headers for the requests
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
# Function to submit a task to the rodin endpoint
def submit_task():
url = f"{base_url}/rodin"
# 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')),
('mesh_mode', (None, 'Raw')),
('quality_override', (None, 500000)),
('material', (None, 'PBR')),
]
# Prepare the headers.
headers = {
'Authorization': f'Bearer {api_key}',
}
# Note that we are not sending the data as JSON, but as form data.
# This is because we are sending a file as well.
response = requests.post(url, files=files, headers=headers)
return response.json()
# Function to check the status of a task
def check_status(subscription_key):
url = f"{base_url}/status"
data = {
"subscription_key": subscription_key
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Function to download the results of a task
def download_results(task_uuid):
url = f"{base_url}/download"
data = {
"task_uuid": task_uuid
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Submit the task and get the task UUID
task_response = submit_task()
task_uuid = task_response['uuid']
subscription_key = task_response['jobs']['subscription_key']
# Poll the status endpoint every 5 seconds until the task is done
status = []
while len(status) == 0 or not all(s['status'] in ['Done', 'Failed'] for s in status):
time.sleep(5)
status_response = check_status(subscription_key)
status = status_response['jobs']
for s in status:
print(f"job {s['uuid']}: {s['status']}")
# Download the results once the task is done
download_response = download_results(task_uuid)
download_items = download_response['list']
# Print the download URLs and download them locally.
for item in download_items:
print(f"File Name: {item['name']}, URL: {item['url']}")
dest_fname = os.path.join(result_path, item['name'])
os.makedirs(os.path.dirname(dest_fname), exist_ok=True)
with open(dest_fname, 'wb') as f:
response = requests.get(item['url'])
f.write(response.content)
print(f"Downloaded {dest_fname}")
```
## Minimal Gen-1&1.5 Regular Example
{% hint style="warning" %}
This script is for demostration purpose only. It lacks some cirtical elements for a production-ready script like error handling.
{% endhint %}
```python
import time
import os
import requests
# Define the base URL, the API key and Paths
base_url = "https://api.hyper3d.com/api/v2"
api_key = "your api key"
image_path = "/your/image/path/robot.jpg"
result_path = "/your/result/path"
# Define the headers for the requests
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
# Function to submit a task to the rodin endpoint
def submit_task():
url = f"{base_url}/rodin"
# 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')),
]
# Set the tier to Rodin Regular
data = {
'tier': 'Regular'
}
# Prepare the headers.
headers = {
'Authorization': f'Bearer {api_key}',
}
# Note that we are not sending the data as JSON, but as form data.
# This is because we are sending a file as well.
response = requests.post(url, files=files, data=data, headers=headers)
return response.json()
# Function to check the status of a task
def check_status(subscription_key):
url = f"{base_url}/status"
data = {
"subscription_key": subscription_key
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Function to download the results of a task
def download_results(task_uuid):
url = f"{base_url}/download"
data = {
"task_uuid": task_uuid
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Submit the task and get the task UUID
task_response = submit_task()
task_uuid = task_response['uuid']
subscription_key = task_response['jobs']['subscription_key']
# Poll the status endpoint every 5 seconds until the task is done
status = []
while len(status) == 0 or not all(s['status'] in ['Done', 'Failed'] for s in status):
time.sleep(5)
status_response = check_status(subscription_key)
status = status_response['jobs']
for s in status:
print(f"job {s['uuid']}: {s['status']}")
# Download the results once the task is done
download_response = download_results(task_uuid)
download_items = download_response['list']
# Print the download URLs and download them locally.
for item in download_items:
print(f"File Name: {item['name']}, URL: {item['url']}")
dest_fname = os.path.join(result_path, item['name'])
os.makedirs(os.path.dirname(dest_fname), exist_ok=True)
with open(dest_fname, 'wb') as f:
response = requests.get(item['url'])
f.write(response.content)
print(f"Downloaded {dest_fname}")
```
# Overview
### **Request Workflow**
The Generation APIs are time and resource consuming, so we designed them to be asynchronous. This means that you submit a task without getting the result immediately.
A typical workflow involves submitting a task to the [Rodin Generation](/api-specification/rodin-generation_reset_v)/[Rodin Gen-2 Generation](/api-specification/rodin-generation-gen2_reset_v) endpoint, [polling for its status](/api-specification/check-status_reset_v), and [downloading the generated files once the task is complete](/api-specification/download-results_reset_v). Refer to the [Minimal Example](/get-started/minimal-example) section for an example script for the workflow.
## **Rodin Gen-2**
Rodin Gen-2 is our most advanced 3D generation model to date. It adopts the brand-new [BANG architecture](https://sites.google.com/view/bang7355608) and is trained with unprecedented 3D data and parameters, reaching a model scale of 10 billion.
Compared to previous versions, Rodin Gen-2 offers the following features:
* 4x improved geometric mesh quality, balancing surface details and structural regularity.
* Recursive part-based generation, dividing and subdividing.
* Support for baked normals to display high-polygon details on low-polygon models.
* HD texture maps.
These features will be gradually rolled out via API in 2025, and you can also access them early on [Hyper3D.AI](https://hyper3d.ai/).
## **Rodin Gen-1&1.5**
### **Rodin Sketch**
Rodin Sketch provides fast generation of 3D models, suitable for early-stage prototyping. It produces models with basic geometry and texturing, allowing for quick visualization and iteration. The textures can be requested in Shaded or PBR formats. The model generated will **only be in GLB format**, thus it will have triangular meshes.
### **Rodin Regular/Detail/Smooth**
Rodin Regular generates 3D models with customizable polygon counts and high-quality texturing. It is ideal for projects that require a good balance of detail and efficiency.
Rodin Detail enhanced details compared to Regular, recommended for intricate results (longer processing time).
Rodin Smooth generate clearer and sharper output than Regular, with slightly longer processing time.
The textures can be requested in Shaded or PBR formats. The model generated can be in a variety of formats (ex. GLB, OBJ, FBX, etc.), and it will have triangular or quad meshes depending on the model format.
#### High Pack Option
For Rodin Regular, the High Pack option can be utilized for even higher resolution (4K) textures and high-poly models. High-poly model is a higher accuracy model, and the number of the high-poly faces is about 16 times the number of general faces.
#### Image-to-3D and Text-to-3D
For Rodin Generation, depending on the task parameters you submit to [Rodin Generation](/api-specification/rodin-generation_reset_v) endpoint, different generation modes are selected. When you upload image files, Rodin selects the Image-to-3D mode. And when you don't upload any image, you have to upload a text prompt, thus the job will be executed in Text-to-3D mode.
#### Multi-Images Generation
For Rodin Image-to-3D Generation, when you upload more than one image to [Rodin Generation](/api-specification/rodin-generation_reset_v) endpoint, it will automatically switch to multi-images generation mode.
You can choose the parameters you submit to [Rodin Generation](/api-specification/rodin-generation_reset_v) endpoint to change the mode of multi-image generation:
* `fuse` mode - if you are uploading images of **multiple objects**, fuse mode will combine all the features of all the objects from the images for generation.
* `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.
***
### Capabilities Comparsion
| MODEL | DESCRIPTION | GENERATION TIME | FEATURES | HIGH PACK |
|---|
| Gen-2 | Most advanced 3D generation model | ~90 seconds | Adjustable polygon counts, high-quality textures (2K texture resolution for Base Pack) | 4K textures
Highpoly for Quad |
| Sketch | Quick, low-resolution 3D asset generation for prototyping | ~20 seconds | Basic geometry + 1K texture, simple UV mapping, low-poly | None |
| Regular | Detailed 3D asset generation with customizable quality | ~70 seconds | Adjustable polygon counts, high-quality textures (2K texture resolution for Base Pack) | 4K textures
Highpoly for Quad |
| Detail | Enhanced details compared to Regular, recommended for intricate results (longer processing time). | > 70 seconds | Adjustable polygon counts, high-quality textures (2K texture resolution for Base Pack) | 4K textures
Highpoly for Quad |
| Smooth | Clearer and sharper output than Regular, with slightly longer processing time. | > 70 seconds | Adjustable polygon counts, high-quality textures (2K texture resolution for Base Pack) | 4K textures
Highpoly for Quad |
# Gen-2 Generation
{% openapi src="/files/4GZzcN6tl62IRIwGJrGN" path="/api/v2/rodin" method="post" %}
[tmp\_gen2.yaml](https://3170127470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fve7H9sNOF32Exg6OAhKo%2Fuploads%2Fgit-blob-1b1889266f089d9cdd86238f28fe566ff6c96e8b%2Ftmp_gen2.yaml?alt=media)
{% endopenapi %}
## 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 ](/api-specification/check-status_reset_v)of the the task and [download the result ](/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 |
|---|
| 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.
None: Asset without material. |
| quality | string | Optional. The face count of the generated model.
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. |
| hd_texture | bool | Optional. Default is false.
If true, high-quality texture will be provided. |
{% 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, 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**: 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://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 | Bussiness subscription is required to use Rodin Gen-2 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 Gen-2 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=Gen-2"
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
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())
```
{% 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
}
// 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)
}
```
{% 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 Gen-2 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" \
-F "tier=Gen-2"
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 Gen-2 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 "images=@/path/to/your/image_0.jpg" \
-F "images=@/path/to/your/image_1.jpg" \
-F "tier=Gen-2"
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
# 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())
```
{% 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 %}
#### Comprehensive Rodin Gen-2 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 "tier=Gen-2" \
-F "prompt=A 3D model of a futuristic robot" \
-F "mesh_mode=Raw" \
-F "seed=42" \
-F "geometry_file_format=fbx" \
-F "material=PBR" \
-F "quality_override=500000" \
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 %}
# Gen-1&1.5 Generation
{% openapi src="/files/QX913xAOD1oDRVz9AdV2" 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 ](/api-specification/check-status_reset_v)of the the task and [download the result ](/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 face count of the generated model.
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 ](/api-specification/check-status_reset_v)and [Download Results](/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 Gen-2.5 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 %}
# 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-5992ce8b06a44b82e041341904c0a55c48d0b44b%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) of the task and [download the result](/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 %}
* **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.
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. |
| image_label | Array of Strings | Optional. Default is [].
An array of directional labels that specifies the orientation of each corresponding input image. The order of the labels must match the order in which the images are uploaded.
Support direction labels:
Front: F
Front-Left: FL
Front-Right: FR
Left: L
Right: R
Back: B
BL: Back-Left
Back-Right: BR
Up: U
Down: D
Unknown: ? |
| 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 creative, 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. |
{% 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/tree/main/developer-apis/api-specification/check-status.md) and [Download Results](https://github.com/Deemos-Technology/docs/tree/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 %}
# Bang!
{% openapi src="/files/eYMhsURuwdnNrsqDMrbX" path="/api/v2/bang" method="post" %}
[BANG.yaml](https://3170127470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fve7H9sNOF32Exg6OAhKo%2Fuploads%2Fgit-blob-b8a0f22d84d1f9e7a2e28c0dbdaa8437f08960c9%2FBANG.yaml?alt=media)
{% endopenapi %}
## Rodin BANG!
Use this API to split a [Rodin-generated Asset](/api-specification/rodin-generation-gen2_reset_v) into multiple submodels.
### Pricing
* **Base Cost**: 0.5 credit per BANG.
### Request
#### 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 |
|---|
| asset_id | string | Parameters asset_id and model are mutually exclusive. Provide only one.
UUID of the Rodin Gen-2 Generation Task. |
| model | file | Parameters asset_id and model are mutually exclusive. Provide only one.
The model used for BANG. Supported model formats are 'obj', 'glb', 'stl', 'fbx', 'usd', 'usda', 'usdz', and 'usdc'. |
| image | file | Optional, Images to be used for texture generate reference. At most One image. And at most 100MB.
The image parameter must be paired with the model parameter. |
| prompt | string | Optional, Prompt to be used for reference.
The prompt parameter must be paired with the model parameter. |
| strength | number | Optional, default: 5, range from 2 - 12. This parameter controls the strength of the splitting of the model. The larger the value, the more pieces there will be. |
| geometry_file_format | string | Required. File format for the generated geometry files. Supported formats: glb, obj, fbx, stl, usdz. Default: glb. |
| material | string | Optional. The material type. Possible values are PBR, Shaded, None 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.
None: Asset without material.
All: Both PBR and Shaded will be delivered. |
| resolution | string | Optional. The resolution of the generated texture assets. Possible values are Basic and High. Default is Basic.
Basic: 2K resolution.
High: 4K resolution. |
{% hint style="info" %}
**How to use Bang! API**
Bang! API supports model segmentation in the following scenarios:
* Generate **Rodin Gen-2** models into parts：
* Required Parameter:
`asset_id`: Provide the `task_uuid` returned from the previous Rodin Gen-2 model generation task.
* Invalid parameters:
`model` must be left empty.
The parameters `image` and `prompt` are not needed for this scenario and will be ignored if provided.
* Generate **custom uploaded** models into parts：
* Required Parameter:
`model`: Provide your model file. Supported formats include: `obj`, `glb`, `stl`, `fbx`, `usd`, `usda`, `usdz`, `usdc`.
`image`: Provide a reference image for generating model textures.
* Invalid parameters:
`asset_id` must be left empty.
* Optional Parameters:
`prompt`: Provide a reference prompt for generating model textures.
{% 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/tree/main/developer-apis/api-specification/check-status.md) and [Download Results](https://github.com/Deemos-Technology/docs/tree/main/developer-apis/api-specification/download-results.md) API endpoints.
{% endhint %}
| 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. |
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 Bang! 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. |
### **Rodin Task Bang! Examples**
{% tabs %}
{% tab title="Request with cURL" %}
```bash
export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/bang \
-H "Authorization: Bearer ${RODIN_API_KEY}" \
-F "asset_id=YOUR_UUID" \
-F "strength=5" \
-F "geometry_file_format=glb" \
-F "material=PBR" \
-F "resolution=Basic" \
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import os
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/bang"
API_KEY = os.getenv("HYPER3D_API_KEY")
UUID = "Your_UUID" # Replace with the UUID of your Rodin Gen-2 Generation Task
# Prepare the data
data = {
'asset_id': UUID,
'strength': 5,
'geometry_file_format': 'glb',
'material': 'PBR',
'resolution': 'Basic',
}
# Prepare the headers
headers = {
'Authorization': f'Bearer {API_KEY}',
}
# Make the POST request
response = requests.post(ENDPOINT, data=data, headers=headers)
# Check if request was successful
if response.status_code == 200:
# Parse and print the JSON response
result = response.json()
print("Success! Task submitted:")
print(f"Task UUID: {result.get('uuid')}")
else:
print(f"Error: {response.status_code}")
print(response.text)
```
{% 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 %}
### **Custom Model Bang! Examples**
{% tabs %}
{% tab title="Request with cURL" %}
```bash
export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/bang \
-H "Authorization: Bearer ${RODIN_API_KEY}" \
-H "Content-Type: multipart/form-data"
-F "model=YOUR_MODEL" \
-F "image=YOUR_IMAGE" \
-F "prompt=YOUR_PROMPT" \
-F "strength=5" \
-F "geometry_file_format=glb" \
-F "material=PBR" \
-F "resolution=Basic" \
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import os
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/bang"
API_KEY = os.getenv("HYPER3D_API_KEY")
UUID = "Your_UUID" # Replace with the UUID of your Rodin Gen-2 Generation Task
IMAGE_PATH = "Your_Image" # Replace with the path of your image
MODEL_PATH = "Your_Model" # Replace with the path of your 3d model
# Prepare the files
# Read the image file
with open(IMAGE_PATH, 'rb') as image_file:
image_data = image_file.read()
with open(MODEL_PATH, 'rb') as model_file:
model_data = model_file.read()
# Prepare the multipart form data
files = {
'image': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg'),
'model': (os.path.basename(IMAGE_PATH), model_data, 'application/octet-stream'),
}
# Prepare the data
data = {
'prompt': "prompt reference."
'strength': 5,
'geometry_file_format': 'glb',
'material': 'PBR',
'resolution': 'Basic',
}
# Prepare the headers
headers = {
'Authorization': f'Bearer {API_KEY}',
}
# Make the POST request
response = requests.post(ENDPOINT, data = data, files = files, headers=headers)
# Check if request was successful
if response.status_code == 200:
# Parse and print the JSON response
result = response.json()
print("Success! Task submitted:")
print(f"Task UUID: {result.get('uuid')}")
else:
print(f"Error: {response.status_code}")
print(response.text)
```
{% 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 %}
# Check Balance
Check the remaining credits in your account.
{% openapi src="/files/Loq5rJmt4RM9YPcKaDp9" path="/api/v2/check\_balance" method="get" %}
[public-api.json](https://3170127470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fve7H9sNOF32Exg6OAhKo%2Fuploads%2Fgit-blob-8b3e8c417bade1e10d0190a05b80cfb0b4f9c3bb%2Fpublic-api.json?alt=media\&token=dadacf4c-0d41-4413-aeb2-aef74447d787)
{% endopenapi %}
Call this API endpoint to check the remaining credits in your account.
### Pricing
We do not charge any addtional credits for calling this API to check your balance.
### Request
#### 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
```
### Response
The JSON response has the following fields.
| Property | Type | Description |
| -------- | ---- | ------------------- |
| balance | int | Balance of account. |
### Examples
{% tabs %}
{% tab title="Request with cURL" %}
```bash
export RODIN_API_KEY="your api key"
curl --location 'https://api.hyper3d.com/api/v2/check_balance' \
--header 'Authorization: Bearer JWT'
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python3" %}
```python
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/check_balance"
API_KEY = os.getenv("HYPER3D_API_KEY")
# Prepare the headers
headers = {
'Authorization': f'Bearer {API_KEY}',
}
# Make the GET request
response = requests.get(ENDPOINT, headers=headers)
# Parse and return the JSON response
print(response.json())
```
{% endtab %}
{% endtabs %}
# Check Status
Check the status of a task submitted to the API.
{% openapi src="/files/Je9OFYyZQsIgvfgeSmOD" path="/api/v2/status" method="post" %}
[Cancel.yaml](https://3170127470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fve7H9sNOF32Exg6OAhKo%2Fuploads%2Fgit-blob-e76a8dee23c33ddbc4b1828853a02009f4d90acf%2FCancel.yaml?alt=media)
{% endopenapi %}
The Generation APIs are time and resource consuming, so we designed them to be asynchronous. This means that you submit a task without getting the result immediately.
{% hint style="warning" %}
Please refrain from calling this API too frequently as it may incur some addtional stress to our servers. We may throttle some requests that are sent too frequently.
{% endhint %}
Instead, your program can then periodically check the status of the task you submitted by supplying the API endpoint the task subscription key you got from your [Generation API call](/api-specification/rodin-generation_reset_v). Once this API tell you that your task has finished, you can safely use the [Download API](/api-specification/download-results_reset_v) to get a list of URLs from where you can download the result models of your task submitted.
The following table lists the possible values from the API call in the `status` field and the semantics of them.
| Status | Meaning |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `Waiting` | Your task has entered our task queue waiting to be scheduled for execution. |
| `Generating` | Our worker is working on generating models for your task. |
| `Done` | The task is done. In this case, you can head to the [Download API](/api-specification/download-results_reset_v) to download the result. |
| `Failed` | The task has failed during execution. In this case, you may need to contact our support for details. |
## Pricing
We do not charge any addtional credits for calling this API to check the status of your task.
## Request
### 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**
The API takes one parameter in the `POST` request body.
| Parameter | Type | Description |
| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **subscription\_key** | **string** | **Required.** The subscription key of the task you want to query the status of. Typically you will get it in the response from the [Generation API](/api-specification/rodin-generation_reset_v). |
## Response
The JSON response has the following fields.
| Property | Type | Description |
| ----------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
| error | string | Optional. Error message, if any. |
| jobs | array of objects | The jobs of the task, containing details of individual jobs executed as part of the generation process. |
| jobs.uuid | string | The uuid of the job. |
| jobs.status | string | The status of the job. The possible values are summarized [in the table above.](#api-v2-status) |
## **Examples**
{% tabs %}
{% tab title="Request with cURL" %}
```sh
export RODIN_API_KEY="your api key"
curl -X 'POST' \
'https://api.hyper3d.com/api/v2/status' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"subscription_key": "your-subscription-key"
}'
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import requests
import os
ENDPOINT = "https://api.hyper3d.com/api/v2/status"
API_KEY = os.getenv("HYPER3D_API_KEY")
SUBSCRIPTION_KEY = "your-subscription-key" # Replace with your actual subscription key
# Prepare the headers
headers = {
'accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': f'Bearer {API_KEY}',
}
# Prepare the JSON payload
data = {
"subscription_key": SUBSCRIPTION_KEY
}
# Make the POST request
response = requests.post(ENDPOINT, headers=headers, json=data)
# Parse and return the JSON response
print(response.json())
```
{% endtab %}
{% tab title="Request with Go" %}
```go
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
const BaseURI = "https://api.hyper3d.com/api"
type CommonError struct {
Error *string `json:"error,omitempty"`
}
type ApiTaskStatusPair struct {
Uuid string `json:"uuid"`
Status string `json:"status"`
}
type ApiStatusResponse struct {
CommonError
Jobs []ApiTaskStatusPair `json:"jobs"`
}
func CheckStatus(token string, subscriptionKey string) (*ApiStatusResponse, error) {
payload := map[string]string{"subscription_key": subscriptionKey}
jsonData, err := json.Marshal(payload)
if err != nil {
return nil, err
}
req, err := http.NewRequest("POST", fmt.Sprintf("%s/v2/status", BaseURI), bytes.NewBuffer(jsonData))
if err != nil {
return nil, err
}
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var responseData ApiStatusResponse
err = json.NewDecoder(resp.Body).Decode(&responseData)
if err != nil {
return nil, err
}
if responseData.Error != nil {
return nil, fmt.Errorf("error: %s", *responseData.Error)
}
return &responseData, nil
}
func main() {
// Replace with your actual API key
token := "your api key"
// Replace with your subscription key
resp, _ := CheckStatus(token, "your subscription key for a task")
fmt.Println(resp)
}
```
{% endtab %}
{% tab title="Response" %}
```json
{
"jobs": [
{
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"status": "Generating"
}
]
}
```
{% endtab %}
{% endtabs %}
# Download Results
Download result for a given task submitted to the API.
{% openapi src="/files/Loq5rJmt4RM9YPcKaDp9" path="/api/v2/download" method="post" %}
[public-api.json](https://3170127470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fve7H9sNOF32Exg6OAhKo%2Fuploads%2Fgit-blob-8b3e8c417bade1e10d0190a05b80cfb0b4f9c3bb%2Fpublic-api.json?alt=media\&token=dadacf4c-0d41-4413-aeb2-aef74447d787)
{% endopenapi %}
Call this API endpoint to get the download URLs for your generation task following a `Done` status returned by the Check Status endpoint.
{% hint style="info" %}
Calling this API endpoint before the task is done may return unexpected results like imcomplete list of files. See [Check Status](/api-specification/check-status_reset_v) for how to see if a task has finished.
{% endhint %}
### Pricing
We do not charge any addtional credits for calling this API to download results of your task.
### Request
#### 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
The API takes one parameter in the `POST` request body.
{% hint style="info" %}
Use the `uuid` field instead of `jobs.uuids` for `task_uuid` in the [response from the Generation API](/api-specification/rodin-generation_reset_v#response).
{% endhint %}
| Parameter | Type | Description |
| -------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **task\_uuid** | **string** | **Required.** The UUID of the task you want to query the status of. Typically you will get it in the response from the Generation API. |
### Response
The JSON response has the following fields. You can download preview\.webp in the list to preview the model.
| Property | Type | Description |
| --------- | ------ | ----------------------------------------------------------------- |
| error | string | Optional. Error message, if any. |
| list | array | The list of the model files available for download for this task. |
| list.url | string | The URL to download the model files from. |
| list.name | string | A human-readable name for the model file. |
### Examples
{% tabs %}
{% tab title="Request with cURL" %}
```bash
export RODIN_API_KEY="your api key"
curl -X 'POST' \
'https://api.hyper3d.com/api/v2/download' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d "{\"task_uuid\": \"your-task-uuid\"}"
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python3" %}
```python
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/download"
API_KEY = os.getenv("HYPER3D_API_KEY")
TASK_UUID = "your-task-uuid" # Replace with your actual task UUID
# Prepare the headers
headers = {
'accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': f'Bearer {API_KEY}',
}
# Prepare the JSON payload
data = {
"task_uuid": TASK_UUID
}
# Make the POST request
response = requests.post(ENDPOINT, headers=headers, json=data)
# Parse and return the JSON response
print(response.json())
```
{% endtab %}
{% tab title="Response" %}
```json
{
"list": [
{
"url": "https://example.com/",
"name": "testfile"
}
]
}
```
{% endtab %}
{% endtabs %}
# Generate Texture
## Texture Generation
{% openapi src="/files/QX913xAOD1oDRVz9AdV2" path="/api/v2/rodin\_texture\_only" 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 %}
## Texture 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 ](/api-specification/check-status_reset_v)of the the task and [download the result ](/api-specification/download-results_reset_v)when the task is ready.
#### Pricing
Each call costs 0.5 credits.
#### 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 |
|---|
| image | file/Binary | Required. One binary image file to serve as texture references. |
| prompt | string | Optional. A texture description to guide texture generation. |
| model | file/Binary | Required. One binary 3D model file to process.
Maximum file size: 10MB |
| 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. |
| reference_scale | number | Optional. Represents the reference scale of texture generation process. |
| 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 and Shaded. Default is PBR.. |
| resolution | string | Optional. The resolution of the output texture. Possible values are Basic and High. Default is Basic. |
#### Examples
{% tabs %}
{% tab title="Request with cURL" %}
```bash
export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/rodin_texture_only \
-H "Authorization: Bearer ${RODIN_API_KEY}" \
-F "image=@/path/to/your/image.jpg" \
-F "model=@path/to/your/model.obj" \
-F "reference_scale=1.0" \
-F "geometry_file_format=glb" \
-F "material=PBR" \
-F "resolution=High"
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/rodin_texture_only"
API_KEY = os.getenv("HYPER3D_API_KEY")
IMAGE_PATH = "/path/to/your/image.jpg" # Replace with the path to your image
MODEL_PATH = "/path/to/your/model.obj"
# Prepare the headers
headers = {
'Authorization': f'Bearer {API_KEY}',
}
# Prepare the form data
files = {
'image': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg'),
'model': (os.path.basename(MODEL_PATH), model_data, 'model/obj'),
'reference_scale': (None, 1.0),
'geometry_file_format': (None, 'glb'),
'material': (None, PBR),
'resolution': (None, 'High'),
}
# Make the POST request
response = requests.post(ENDPOINT, headers=headers, files=files)
# Parse and return the JSON response
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 %}
# Data Retention Policy
Your data, and your users' data, are secure with us. We guarantee that your data will be securely stored for **7 days**, will **not** be used for training purposes, and will **not** be shared without your explicit consent. Additionally, any model generated using our API will **not** appear in any user's ASSETS tab.
For more information, please refer to our Privacy Policy and Terms of Service. If you have any concerns, feel free to reach out to us.
# Get started with Rodin
Rodin 的 API 使用 API 密钥来验证请求。要以编程方式访问 Rodin 服务，您需要生成一个 API 密钥。以下是如何安全地进行身份验证和使用 API 密钥的步骤。
#### 生成 API 密钥
1. **导航到 API 密钥管理页面**
* 登录到您的 Rodin 账户，进入 API 密钥管理部分。
* 点击“+创建新 API 密钥”按钮以生成新密钥。
2. **安全存储您的 API 密钥**
* 一旦创建，API 密钥将仅显示一次。确保您复制并安全存储。如果您丢失了密钥，您需要生成一个新密钥。
3. **在必要时撤销密钥**
* 您可以直接在 API 密钥管理页面管理现有的 API 密钥，并撤销不再需要的密钥。
#### **使用 API 密钥进行身份验证**
对于每个 API 请求，请在 Authorization HTTP 头中包含 API 密钥。以下是如何构建请求的示例：
```http
Authorization: Bearer YOUR_RODIN_API_KEY
```
将 `YOUR_RODIN_API_KEY` 替换为您实际生成的 API 密钥。
### 发起请求
一旦您生成了 API 密钥，就可以使用以下示例代码触发您的第一个请求，以生成高质量的 3D 资产。
{% tabs %}
{% tab title="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="Python 3" %}
{% code fullWidth="false" %}
```
// 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
```
{% endcode %}
{% endtab %}
{% endtabs %}
# Minimal Example
## Minimal Gen-2 Example
{% hint style="warning" %}
此脚本仅用于演示目的。它缺少一些用于生产环境的脚本的关键元素，如错误处理。
{% endhint %}
```python
import time
import os
import requests
# Define the base URL, the API key and Paths
base_url = "https://api.hyper3d.com/api/v2"
api_key = "your api key"
image_path = "/your/image/path/robot.jpg"
result_path = "/your/result/path"
# Define the headers for the requests
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
# Function to submit a task to the rodin endpoint
def submit_task():
url = f"{base_url}/rodin"
# 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'),
'mesh_mode': (None, 'Raw'),
'quality_override': (None, 500000),
'material': (None, 'PBR')
}
# Prepare the headers.
headers = {
'Authorization': f'Bearer {api_key}',
}
# Note that we are not sending the data as JSON, but as form data.
# This is because we are sending a file as well.
response = requests.post(url, files=files, headers=headers)
return response.json()
# Function to check the status of a task
def check_status(subscription_key):
url = f"{base_url}/status"
data = {
"subscription_key": subscription_key
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Function to download the results of a task
def download_results(task_uuid):
url = f"{base_url}/download"
data = {
"task_uuid": task_uuid
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Submit the task and get the task UUID
task_response = submit_task()
task_uuid = task_response['uuid']
subscription_key = task_response['jobs']['subscription_key']
# Poll the status endpoint every 5 seconds until the task is done
status = []
while len(status) == 0 or not all(s['status'] in ['Done', 'Failed'] for s in status):
time.sleep(5)
status_response = check_status(subscription_key)
status = status_response['jobs']
for s in status:
print(f"job {s['uuid']}: {s['status']}")
# Download the results once the task is done
download_response = download_results(task_uuid)
download_items = download_response['list']
# Print the download URLs and download them locally.
for item in download_items:
print(f"File Name: {item['name']}, URL: {item['url']}")
dest_fname = os.path.join(result_path, item['name'])
os.makedirs(os.path.dirname(dest_fname), exist_ok=True)
with open(dest_fname, 'wb') as f:
response = requests.get(item['url'])
f.write(response.content)
print(f"Downloaded {dest_fname}")
```
## Minimal Gen-1&1.5 Regular Example
{% hint style="warning" %}
此脚本仅用于演示目的。它缺少一些用于生产环境的脚本的关键元素，如错误处理。
{% endhint %}
```python
import time
import os
import requests
# Define the base URL, the API key and Paths
base_url = "https://api.hyper3d.com/api/v2"
api_key = "your api key"
image_path = "/your/image/path/robot.jpg"
result_path = "/your/result/path"
# Define the headers for the requests
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
# Function to submit a task to the rodin endpoint
def submit_task():
url = f"{base_url}/rodin"
# 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')
}
# Set the tier to Rodin Regular
data = {
'tier': 'Regular'
}
# Prepare the headers.
headers = {
'Authorization': f'Bearer {api_key}',
}
# Note that we are not sending the data as JSON, but as form data.
# This is because we are sending a file as well.
response = requests.post(url, files=files, data=data, headers=headers)
return response.json()
# Function to check the status of a task
def check_status(subscription_key):
url = f"{base_url}/status"
data = {
"subscription_key": subscription_key
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Function to download the results of a task
def download_results(task_uuid):
url = f"{base_url}/download"
data = {
"task_uuid": task_uuid
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Submit the task and get the task UUID
task_response = submit_task()
task_uuid = task_response['uuid']
subscription_key = task_response['jobs']['subscription_key']
# Poll the status endpoint every 5 seconds until the task is done
status = []
while len(status) == 0 or not all(s['status'] in ['Done', 'Failed'] for s in status):
time.sleep(5)
status_response = check_status(subscription_key)
status = status_response['jobs']
for s in status:
print(f"job {s['uuid']}: {s['status']}")
# Download the results once the task is done
download_response = download_results(task_uuid)
download_items = download_response['list']
# Print the download URLs and download them locally.
for item in download_items:
print(f"File Name: {item['name']}, URL: {item['url']}")
dest_fname = os.path.join(result_path, item['name'])
os.makedirs(os.path.dirname(dest_fname), exist_ok=True)
with open(dest_fname, 'wb') as f:
response = requests.get(item['url'])
f.write(response.content)
print(f"Downloaded {dest_fname}")
```
# Overview
### **请求工作流**
API生成模型消耗资源和时间，因此我们将其设计为异步的。这意味着你提交了一个生成任务后并不一定能立即得到结果。
一个典型的工作流程包括将任务提交到[Rodin 生成](/zh_cn/api-specification/rodin-generation_reset_v)/[Rodin Gen-2 生成](/zh_cn/api-specification/rodin-generation-gen2_reset_v)端点，[状态查询](/zh_cn/api-specification/check-status_reset_v)端点，以及[当任务完成后获取下载链接的](/zh_cn/api-specification/download-results_reset_v)端点。有关工作流的示例脚本请参阅[Minimal Example](/zh_cn/get-started/minimal-example)。
## **Rodin Gen-2**
Rodin Gen-2是我们目前最先进的3D生成模型。它采用了全新的[BANG架构](https://sites.google.com/view/bang7355608)，使用了前所未有的3D数据与参数量来训练，模型规模到达了10B量级。
相比之前的版本，Rodin Gen-2有如下特点：
* 4倍几何网格质量，平衡了表面细节与结构规整度
* 递归式分件生成，分了再分
* 支持通过烘焙法线，在低面模型下展示高面模型的细节
* 高清材质贴图
这些功能会在2025年相继完成API的上线，您也可以在[Hyper3D.AI](https://hyper3d.ai/)中提前使用。
## **Rodin Gen-1&1.5**
### **Rodin Sketch**
Rodin Sketch提供了快速生成3D模型，适用于早期的原型设计。它生成具有基本几何和纹理的模型，可以快速可视化或迭代。Rodin Sketch**仅提供GLB格式**的模型，因此它将是三角面模型。
### **Rodin Regular**
Rodin Regular生成具有自定义面数和高质量纹理的3D模型。它非常适合需要在细节和效率之间取得良好平衡的项目。纹理可以选择Shaded或PBR格式。生成的模型可以选择多种格式（如GLB,OBJ,FBX等等），并根据所选模型格式提供相对应的三角面或四角面模型。
#### High Pack Option
对于Rodin Regular,High Pack 选项可以生成更高分辨率(4K)的纹理和High-poly的模型。High-poly模型拥有更高的精度，它的面数是正常所选模型面数的16倍左右。
#### Image-to-3D 和 Text-to-3D
Rodin会根据您提交给[Rodin Generation](/zh_cn/api-specification/rodin-generation_reset_v)端点的参数的不同，选择不同的生成模式。当您将图片文件作为参数上传时，Rodin会选用Image-to-3D模式。当您没有上传任何图片文件时，则必须上传prompt，此时将会以Text-to-3D模式执行。
#### 多图片生成模型
对于 Rodin 的 Image-to-3D 生成，当你向 [Rodin Generation](/zh_cn/api-specification/rodin-generation_reset_v) 端点上传多于一张图片时，它会自动切换到多图像生成模型模式。
你可以选择提交给 [Rodin Generation](/zh_cn/api-specification/rodin-generation_reset_v) 端点的参数，以改变多图像生成的模式。
* fuse 模式将结合所有图像的特征进行生成。
* concat 模式期望这些图像是单个模型的多视图图像。
***
### Capabilities Comparsion
| 模式 | 描述 | 生成时间（预计） | 特点 | HighPack |
|---|
| Gen-2 | 最先进的3D生成模型 | ~90 秒 | 可调面数，高质量的纹理（Base Pack提供 2K 纹理）。 | 4K 纹理
HighPoly(Quad模式) |
| Sketch | 快速的，低分辨率的原型 3D 资产生成。 | ~20 秒 | 基本几何，简单的UV映射，低多边形。 | 无 |
| Regular | 可定制质量的详细3D资产生成。 | ~70 秒 | 可调面数，高质量的纹理（Base Pack提供 2K 纹理）。 | 4K 纹理
HighPoly(Quad模式) |
| Detail | 比 Regular 更丰富的细节表现，适合复杂需求（生成时间更长）。 | >70 秒 | 可调面数，高质量的纹理（Base Pack提供 2K 纹理）。 | 4K 纹理
HighPoly(Quad模式) |
| Smooth | 比 Regular 更清晰锐利的输出效果，生成时间略长。 | >70 秒 | 可调面数，高质量的纹理（Base Pack提供 2K 纹理）。 | 4K 纹理
HighPoly(Quad模式) |
# Gen-2 Generation
{% openapi src="/files/hUxAth70CiEv2PptydV3" path="/api/v2/rodin" method="post" %}
[tmp\_gen2.yaml](https://563398440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiMYwiLTHWAzkgBEpY5K%2Fuploads%2Fgit-blob-1b1889266f089d9cdd86238f28fe566ff6c96e8b%2Ftmp_gen2.yaml?alt=media)
{% endopenapi %}
## Rodin生成
### ***请求时调用参数 'tier=Gen-2' 以使用Gen-2生成模型***
使用此API向我们的服务器提交异步任务。你将从API中获得一个任务UUID，该UUID可用于[ 检查进度 ](/zh_cn/api-specification/check-status_reset_v)和[ 下载结果 ](/zh_cn/api-specification/download-results_reset_v)。
### 价格
{% hint style="info" %}
**Note**: 参数不会收取任何额外费用，只有模型附加项才会有额外收费。
{% endhint %}
* **Base Cost**: 每次生成消耗 0.5 Credit。
* **Addons**:
* `HighPack`: 每次生成额外消耗 1 Credit。
### 请求
{% hint style="info" %}
**Note**: 所有到这个端点的请求都必须使用`multipart/form-data`发送，以正确处理文件上传以及网格和纹理生成过程所需的其他参数。
{% endhint %}
#### Authentication
此API使用密钥进行身份验证。您需要在所有请求的`Authorization`头中包含一个有效的密钥. 参阅[快速开始](/zh_cn#authentication-for-rodin-api)获取您的账户的API生成密钥。
```
Authorization: Bearer RODIN_API_KEY
```
#### **Body**
| 参数 | 类型 | 描述 |
|---|
| tier | string | 将该参数值设置为Gen-2来调用Gen-2生成模型。
必须！
默认值为Regular。 |
| images | file/Binary | 用于图像生成，最多上传5张图片。由于form-data请求将保留图像的顺序，因此将会使用上传列表的第一张图片来生成材质贴图。
对于Image-to-3D模式，图片是必须的。可上传一张或多张图片。（最多上传5张图片。）
对于Text-to-3D模式，则不需要上传图片。 |
| prompt | string | 用于指导模型生成的文本提示。
对于Image-to-3D生成模式是可选的。(如果没有提供，将使用基于提供的图像的人工智能生成的提示。)
对Text-to-3D模式是必须的。 |
| use_original_alpha | boolean | 默认是false. 如果 True, 上传图像的透明度通道将会直接被用于图片处理。 |
| seed | number | 可选的。网格生成中用于随机化的种子值，范围从0到65535(包括两者)。如果不提供，种子将随机生成。 |
| geometry_file_format | string | 可选的。模型文件的格式。可能的值为glb，usdz，fbx，obj，stl。默认值为glb。 |
| material | string | 可选的。材质类型。可能的值为PBR，Shaded和All。默认值为PBR。
PBR：物理基础材质，包括基础颜色纹理、金属度纹理、法线纹理和粗糙度纹理，提供高真实感并在动态光照下具有物理准确性。
Shaded：仅包含基础颜色纹理和烘焙光照，提供风格化的视觉效果。
All：会同时生成PBR和Shaded材质。
None: 无材质。 |
| quality | string | 可选的。控制生成模型的面数。
可选值有high, medium, low, 和extra-low.
当mesh_mode为Raw时: high: 500k, medium: 150k, low: 20k, extra-low: 2k, 默认值为high。
当mesh_mode为Quad时: high: 50k, medium: 18k, low: 8k, extra-low: 4k, 默认值为medium。 |
| TAPose | bool | 可选的。控制生成类人模型时，生成结果展现为T/A Pose。
当该值为true时，生成的模型将为Tpose或者Apose。 |
| bbox_condition | Array of Integer | 可选的。该参数是一个控制生成模型最大生成边界的control net.
通常来说，这个数组包含三个元素，分别是宽度（y轴），高度（z轴）和长度（x轴）。 |
| mesh_mode | string | 可选的，可选的值有Raw和Quad. 默认值为Quad.
Raw模式会生成三角面模型。
Quad模式生成四边面模型。 |
| addons | array of strings | 可选的。生成附加功能。默认为[]。可能的值为HighPack.
当选择HighPack选项时：
提供4K分辨率的纹理贴图而不是基础的2K分辨率。
当mesh_mode为Quad时，还会提供更高面数的模型文件。(约16倍选择quality对应面数。) |
| preview_render | bool | 可选的， 默认为false.
如果true，生成结束后的下载列表中将会额外多一张高质量渲染图像。 |
| hd_texture | bool | 可选的， 默认为false.
如果true，高质量纹理贴图。 |
{% hint style="info" %}
Rodin 提供了两种生成模式:
* **Image-to-3D**:
当你上传**一张或多张** `images` 时，将会自动启用图生3D模式。
* 单一图片: 上传**一张**图片来生成3D模型。
* 多图片: 将所有上传图片作为同一物体的多视角图片进行3D模型生成。**上传图片的第一张图片将作为贴图生成的参考图**。
**注意**: Form data 请求体会维持你上传图片的顺序，确保你上传图片的顺序正确。
* **Text-to-3D**:
当你没有上传任何`images`时，将自动启用文生3D模式。
* 必须参数:
`prompt`: 你必须提供提示词来指导模型的生成。
* 重要: 当时使用Text-to-3D时，请勿输入`images`参数的值。
{% endhint %}
{% hint style="info" %}
**ControlNet**: ControlNet通过对生成的输出提供更精细的控制来增强模型定制。它在原始API的基础上添加了几个参数，允许用户操作3D模型的比例、形状和结构等方面。
ControlNet引入以下主要参数，以提供对模型生成过程的高级控制：
* **BoundingBox ControlNet**: BoundingBox ControlNet允许用户通过可拖动的边界框指定长度、宽度和高度来定义生成模型的比例。当您希望生成的对象适合特定的尺寸或遵循特定的空间约束时，这尤其有用。
* 样例：
```
{
"bbox_condition": [
100,
100,
100
]
}
```
* **bbox\_condition**: 指定边界框的尺寸和缩放因子的数组。
* 元素:
1. Width (Y-axis):`100` units.
2. Height (Z-axis):`100` units.
3. Length (X-axis):`100` uints.
通过设置 `bbox_condition`，您将指示模型生成一个适合指定尺寸的长方体对象。
* **Bounding Box Axis**:
```
World
+z(Height)
|
|
|______+y(Width)
/
/
/
+x(Length)
```
{% endhint %}
### **响应**
{% hint style="info" %}
对于[response from the Generation API](/zh_cn/api-specification/rodin-generation_reset_v#response)的`task_uuid`，使用`uuid`字段替代`jobs_uuid`。
{% endhint %}
| Property | Type | Description |
|---|
| error | enum | 错误信息（如有）。 |
| message | string | 成功信息或详细的错误信息。 |
| uuid | string | 生成任务的唯一标识符。 |
| jobs | object | 一个作业对象，包含作为生成过程一部分执行的各个作业的详细信息。 |
| jobs.uuids | array of strings | 子任务的UUIDs。 |
| jobs.subscription_key | string | 任务密钥 |
可能出现的报错信息包括:
| Error | 描述 |
|---|
| NO_ACTIVE_SUBSCRIPTION | 没有有效订阅或订阅已经过期。 |
| SUBSCRIPTION_PLAN_TOO_LOW | 当前订阅计划等级过低，需要商业计划以使用API功能。 |
| INSUFFICIENT_FUND | 用户账户余额不足，无法完成请求的操作。 |
| INVALID_REQUEST | 请求格式错误、缺少必要参数或包含无效值。可查看message以获得更多错误信息。 |
| USER_NOT_FOUND | 使用了无效的API KEY或用户不存在。 |
| GROUP_NOT_FOUND | 使用了无效的API KEY或用户分组不存在。 |
| PERMISSION_DENIED | 经过身份验证的用户无权执行此操作。 |
| UNKNOWN | 发生了意外的错误。检查message以获得更多错误信息。 |
### **代码示例**
#### Minimal Rodin Gen-2 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=Gen-2"
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
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())
```
{% 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
}
// 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)
}
```
{% 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 Gen-2 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" \
-F "tier=Gen-2"
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 Gen-2 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" \
-F "tier=Gen-2"
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
# 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())
```
{% 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 %}
#### Comprehensive Rodin Gen-2 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 "tier=Gen-2" \
-F "prompt=A 3D model of a futuristic robot" \
-F "mesh_mode=Raw" \
-F "seed=42" \
-F "geometry_file_format=fbx" \
-F "material=PBR" \
-F "quality_override=500000" \
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 %}
# Gen-1&1.5 Generation
{% openapi src="/files/5w81V2d3ohxMjZNUCiOF" path="/api/v2/rodin" method="post" %}
[tmp.yaml](https://563398440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiMYwiLTHWAzkgBEpY5K%2Fuploads%2Fgit-blob-74b44ac4fa8f9db435ebd9d2d2be7fc11aca2bbd%2Ftmp.yaml?alt=media)
{% endopenapi %}
## Rodin生成
使用此API向我们的服务器提交异步任务。你将从API中获得一个任务UUID，该UUID可用于[ 检查进度 ](/zh_cn/api-specification/check-status_reset_v)和[ 下载结果 ](/zh_cn/api-specification/download-results_reset_v)。
### 价格
{% hint style="info" %}
**Note**: 参数不会收取任何额外费用，只有模型附加项才会有额外收费。
{% endhint %}
* **Base Cost**: 每次生成消耗 0.5 Credit。
* **Addons**:
* `HighPack`: 每次生成额外消耗 1 Credit。
### 请求
{% hint style="info" %}
**Note**: 所有到这个端点的请求都必须使用`multipart/form-data`发送，以正确处理文件上传以及网格和纹理生成过程所需的其他参数。
{% endhint %}
#### Authentication
此API使用密钥进行身份验证。您需要在所有请求的`Authorization`头中包含一个有效的密钥. 参阅[快速开始](/zh_cn#authentication-for-rodin-api)获取您的账户的API生成密钥。
```
Authorization: Bearer RODIN_API_KEY
```
#### **Body**
| 参数 | 类型 | 描述 |
|---|
| images | file/Binary | 用于图像生成，最多上传5张图片。由于form-data请求将保留图像的顺序，因此将会使用上传列表的第一张图片来生成材质贴图。
对于Image-to-3D模式，图片是必须的。可上传一张或多张图片。（最多上传5张图片。）
对于Text-to-3D模式，则不需要上传图片。 |
| prompt | string | 用于指导模型生成的文本提示。
对于Image-to-3D生成模式是可选的。(如果没有提供，将使用基于提供的图像的人工智能生成的提示。)
对Text-to-3D模式是必须的。 |
| use_original_alpha | boolean | 默认是false. 如果 True, 上传图像的透明度通道将会直接被用于图片处理。 |
| condition_mode | string | 该参数仅用于多图像生成。
这是一个可选的参数，用于选择多图生成时的生成方式。可能的值为fuse或concat。默认值为concat。
对于fuse 模式，需要上传一张或多张图片。可以融合多张图片的物体特征生成一个模型。
对于concat模式，需要上传同一物体的多张多视角图片，并生成该模型。（无须在意上传图片的顺序。） |
| seed | number | 可选的。网格生成中用于随机化的种子值，范围从0到65535(包括两者)。如果不提供，种子将随机生成。 |
| geometry_file_format | string | 可选的。模型文件的格式。可能的值为glb，usdz，fbx，obj，stl。默认值为glb。 |
| material | string | 可选的。材质类型。可能的值为PBR，Shaded和All。默认值为PBR。
PBR：物理基础材质，包括基础颜色纹理、金属度纹理、法线纹理和粗糙度纹理，提供高真实感并在动态光照下具有物理准确性。
Shaded：仅包含基础颜色纹理和烘焙光照，提供风格化的视觉效果。
All：会同时生成PBR和Shaded材质。
None: 无材质。 |
| quality | string | 可选的。生成模型的面数。可能的值为high(50k面), medium(18k面), low(8k面), 和extra-low(4k面)。默认值为medium。
对于Rodin Sketch，该值仅为medium时生效。 |
| quality_override | number | 可选的。自定义生成模型的面数。范围从2000到200000面，可对网格面数提供更精确的控制。
该参数为quality参数的进阶参数。当调用该参数时，quality参数不会生效。
对于Rodin Sketch，该参数不会生效，模型面数设置为quality参数的默认值。 |
| tier | string | 可选的。默认值为Regular。
Sketch：快速生成，细节较少，适合概念草图或初步构思。
Regular：兼顾速度与质量的生成，适用于大多数场景（默认选项）。
Detail：比 Regular 更丰富的细节表现，适合复杂需求（生成时间更长）。
Smooth：比 Regular 更清晰锐利的输出效果，生成时间略长。 |
| TAPose | bool | 可选的。控制生成类人模型时，生成结果展现为T/A Pose。
当该值为true时，生成的模型将为Tpose或者Apose。 |
| bbox_condition | Array of Integer | 可选的。该参数是一个控制生成模型最大生成边界的control net.
通常来说，这个数组包含三个元素，分别是宽度（y轴），高度（z轴）和长度（x轴）。 |
| mesh_mode | string | 可选的，可选的值有Raw和Quad. 默认值为Quad.
Raw模式会生成三角面模型。
Quad模式生成四边面模型。
当tier为Sketch：仅生成三角面。 |
| mesh_simplify | bool | 可选的。当值为true时，将会生成简化模型。
该参数仅当mesh_mode的值为Raw时生效。 |
| mesh_smooth | bool | 可选的。当值为true时，将会生成平滑模型（效果等同于Rodin Gen-1）。
该参数仅当mesh_mode的值为Quad时生效。 |
| addons | array of strings | 可选的。生成附加功能。默认为[]。可能的值为HighPack.
当选择HighPack选项时：
提供4K分辨率的纹理贴图而不是基础的2K分辨率。
当mesh_mode为Quad时，还会提供更高面数的模型文件。(约16倍选择quality对应面数。) |
preview\_renderbool可选的， 默认为`false`.\
如果`true`，生成结束后的下载列表中将会额外多一张高质量渲染图像。
{% hint style="info" %}
Rodin 提供了两种生成模式:
* **Image-to-3D**:
当你上传**一张或多张** `images` 时，将会自动启用图生3D模式。
* 单一图片: 上传**一张**图片来生成3D模型。
* 多图片: 上传**多张**图片来生成3D模型，此时你还需要考虑如下两种情况：
`fuse` 模式: 将你上传的所有图片中物体的特征进行融合，最终生成3D模型。
`concat` 模式: 将所有上传图片作为同一物体的多视角图片进行3D模型生成。**上传图片的第一张图片将作为贴图生成的参考图**。
**注意**: Form data 请求体会维持你上传图片的顺序，确保你上传图片的顺序正确，尤其是你要使用`concat`模式的情况下。
* **Text-to-3D**:
当你没有上传任何`images`时，将自动启用文生3D模式。
* 必须参数:
`prompt`: 你必须提供提示词来指导模型的生成。
* 重要: 当时使用Text-to-3D时，请勿输入`images`参数的值。
{% endhint %}
{% hint style="info" %}
**ControlNet**: ControlNet通过对生成的输出提供更精细的控制来增强模型定制。它在原始API的基础上添加了几个参数，允许用户操作3D模型的比例、形状和结构等方面。
ControlNet引入以下主要参数，以提供对模型生成过程的高级控制：
* **BoundingBox ControlNet**: BoundingBox ControlNet允许用户通过可拖动的边界框指定长度、宽度和高度来定义生成模型的比例。当您希望生成的对象适合特定的尺寸或遵循特定的空间约束时，这尤其有用。
* 样例：
```
{
"bbox_condition": [
100,
100,
100
]
}
```
* **bbox\_condition**: 指定边界框的尺寸和缩放因子的数组。
* 元素:
1. Width (Y-axis):`100` units.
2. Height (Z-axis):`100` units.
3. Length (X-axis):`100` uints.
通过设置 `bbox_condition`，您将指示模型生成一个适合指定尺寸的长方体对象。
* **Bounding Box Axis**:
```
World
+z(Height)
|
|
|______+y(Width)
/
/
/
+x(Length)
```
{% endhint %}
### **响应**
{% hint style="info" %}
对于[response from the Generation API](#response)的`task_uuid`，使用`uuid`字段替代`jobs_uuid`。
{% endhint %}
| Property | Type | Description |
|---|
| error | enum | 错误信息（如有）。 |
| message | string | 成功信息或详细的错误信息。 |
| uuid | string | 生成任务的唯一标识符。 |
| jobs | object | 一个作业对象，包含作为生成过程一部分执行的各个作业的详细信息。 |
| jobs.uuids | array of strings | 子任务的UUIDs。 |
| jobs.subscription_key | string | 任务密钥 |
Possible Errors include:
| Error | 描述 |
|---|
| NO_ACTIVE_SUBSCRIPTION | 没有有效订阅或订阅已经过期。 |
| SUBSCRIPTION_PLAN_TOO_LOW | 当前订阅计划等级过低，需要商业计划以使用API功能。 |
| INSUFFICIENT_FUND | 用户账户余额不足，无法完成请求的操作。 |
| INVALID_REQUEST | 请求格式错误、缺少必要参数或包含无效值。可查看message以获得更多错误信息。 |
| USER_NOT_FOUND | 使用了无效的API KEY或用户不存在。 |
| GROUP_NOT_FOUND | 使用了无效的API KEY或用户分组不存在。 |
| PERMISSION_DENIED | 经过身份验证的用户无权执行此操作。 |
| UNKNOWN | 发生了意外的错误。检查message以获得更多错误信息。 |
### **代码示例**
#### 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
files = [
('images', (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg')),
]
# Set the tier to Rodin Sketch
data = {
'tier': 'Sketch',
}
# Prepare the headers
headers = {
'Authorization': f'Bearer {API_KEY}',
}
# Make the POST request
response = requests.post(ENDPOINT, files=files, data=data, 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 "use_hyper=true" \
-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 %}
# Bang!
{% openapi src="/files/rOzkWiWgOLYSFC9mKS3f" path="/api/v2/bang" method="post" %}
[BANG.yaml](https://563398440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiMYwiLTHWAzkgBEpY5K%2Fuploads%2Fgit-blob-b8a0f22d84d1f9e7a2e28c0dbdaa8437f08960c9%2FBANG.yaml?alt=media)
{% endopenapi %}
## Rodin BANG!
使用此API可将[Rodin生成的资产](/zh_cn/api-specification/rodin-generation-gen2_reset_v)分割为多个子模型。
**注意**：此节点只能使用由**Rodin Gen-2**生成的模型。
### 价格
* **基本费用**：每次BANG 消耗0.5个积分。
### 请求
#### 认证
此API使用Bearer密钥进行认证。所有请求必须在`Authorization`头中包含有效的令牌。
```
Authorization: Bearer RODIN_API_KEY
```
#### **请求体**
| 参数 | 类型 | 描述 |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| asset\_id | string | model 与 asset\_id 二选一。
Rodin Gen-2生成任务的UUID。
|
| model | file | model 与 asset\_id 二选一。
该参数为进行Bang! 的自定义模型，可以支持的模型格式有：obj, glb, stl, fbx, usd, usda, usdz, and usdc.
|
| image | file | 可选，模型生成参考用图。
该参数必须搭配model参数使用。
|
| prompt | string | 可选，模型生成参考用提示词。
该参数必须搭配model参数使用。
|
| strength | number | 可选，默认：5，范围2-12。此参数控制模型分割的强度。值越大，生成的碎片越多。 |
| geometry\_file\_format | string | 必填。生成的几何文件格式。支持的格式：`glb`、`obj`、`fbx`、`stl`、`usdz`。默认值：`glb`。 |
| material | string | 可选。材质类型。可能的值为PBR、Shaded、None和All。默认值为PBR。
PBR：基于物理的材质，包括基础颜色纹理、金属度纹理、法线纹理和粗糙度纹理，提供高真实感和动态光照下的物理准确性。
Shaded：仅包含烘焙光照的基础颜色纹理，提供风格化视觉效果。
None：无材质资产。
All：将同时提供PBR和Shaded两种材质。
|
| resolution | string | 可选。生成贴图资产的分辨率。可能的值为Basic、High。默认值为Basic。
Basic：2K分辨率。
High：4K分辨率。
|
{% hint style="info" %}
**如何使用 Bang! API**
Bang! API 支持以下两种情景的模型分件:
* 对 **Rodin Gen-2** 生成的模型进行分件：
* 必须参数:
`asset_id`: 提供由 **Rodin Gen-2** API节点返回的 `task_uuid`。
* 无效参数:
`model` 参数 **必须为空**。
`image` 和 `prompt` 这三个参数在此场景下**无需传入**，即使传入也会被忽略。
* 对 **自定义上传模型** 进行分件：
* 必须参数:
`model`: 提供你的自定义模型，支持的3D模型格式包括 `obj`, `glb`, `stl`, `fbx`, `usd`, `usda`, `usdz`, `usdc`.
`image`: 上传参考图片，用于模型贴图的生成。
* 无效参数:
`asset_id` 参数 **必须为空**。
* 可选参数:
`prompt`: 上传参考提示词，用于模型贴图生成
{% endhint %}
### **响应**
{% hint style="info" %}
在请求[检查状态](/zh_cn/api-specification/check-status_reset_v)和[下载结果](/zh_cn/api-specification/download-results_reset_v)API端点时，请使用`uuid`字段而非`jobs.uuids`字段。
{% endhint %}
| 属性 | 类型 | 描述 |
| ---------------------- | ---------------- | ------------------------------ |
| error | string | 错误信息（如有）。 |
| message | string | 成功消息或详细错误信息。 |
| uuid | string | 生成任务的唯一标识符。 |
| jobs | object | 任务对象，包含作为生成过程一部分执行的各个子任务的详细信息。 |
| jobs.uuids | array of strings | 子任务的UUID列表。 |
| jobs.subscription\_key | string | 与这些任务关联的订阅密钥。 |
可能出现的报错信息包括:
| Error | 描述 |
|---|
| NO_ACTIVE_SUBSCRIPTION | 没有有效订阅或订阅已经过期。 |
| SUBSCRIPTION_PLAN_TOO_LOW | 当前订阅计划等级过低，需要商业计划以使用API功能。 |
| INSUFFICIENT_FUND | 用户账户余额不足，无法完成请求的操作。 |
| INVALID_REQUEST | 请求格式错误、缺少必要参数或包含无效值。可查看message以获得更多错误信息。 |
| USER_NOT_FOUND | 使用了无效的API KEY或用户不存在。 |
| GROUP_NOT_FOUND | 使用了无效的API KEY或用户分组不存在。 |
| PERMISSION_DENIED | 经过身份验证的用户无权执行此操作。 |
| UNKNOWN | 发生了意外的错误。检查message以获得更多错误信息。 |
### **Rodin任务Bang!示例**
{% tabs %}
{% tab title="使用cURL发送请求" %}
```bash
export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/bang \
-H "Authorization: Bearer ${RODIN_API_KEY}" \
-d "asset_id=YOUR_UUID" \
-d "strength=5" \
-d "geometry_file_format=glb" \
-d "material=PBR" \
-d "resolution=Basic" \
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="使用Python 3发送请求" %}
```python
import os
import requests
# 常量
ENDPOINT = "https://api.hyper3d.com/api/v2/bang"
API_KEY = os.getenv("HYPER3D_API_KEY")
UUID = "Your_UUID" # 替换为您的Rodin Gen-2生成任务的UUID
# 准备表单数据
data = {
'asset_id': UUID,
'strength': 5,
'geometry_file_format': 'glb',
'material': 'PBR',
'resolution': 'Basic',
}
# 准备请求头
headers = {
'Authorization': f'Bearer {API_KEY}',
}
# 发送POST请求
response = requests.post(ENDPOINT, data=data, headers=headers)
# 检查请求是否成功
if response.status_code == 200:
# 解析并打印JSON响应
result = response.json()
print("成功！任务已提交：")
print(f"任务UUID: {result.get('uuid')}")
else:
print(f"错误: {response.status_code}")
print(response.text)
```
{% endtab %}
{% tab title="响应" %}
```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 %}
### **自定义模型Bang! 示例**
{% tabs %}
{% tab title="Request with cURL" %}
```bash
export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/bang \
-H "Authorization: Bearer ${RODIN_API_KEY}" \
-H "Content-Type: multipart/form-data"
-F "model=YOUR_MODEL" \
-F "image=YOUR_IMAGE" \
-F "prompt=YOUR_PROMPT" \
-F "strength=5" \
-F "geometry_file_format=glb" \
-F "material=PBR" \
-F "resolution=Basic" \
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import os
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/bang"
API_KEY = os.getenv("HYPER3D_API_KEY")
UUID = "Your_UUID" # Replace with the UUID of your Rodin Gen-2 Generation Task
IMAGE_PATH = "Your_Image" # Replace with the path of your image
MODEL_PATH = "Your_Model" # Replace with the path of your 3d model
# Prepare the files
# Read the image file
with open(IMAGE_PATH, 'rb') as image_file:
image_data = image_file.read()
with open(MODEL_PATH, 'rb') as model_file:
model_data = model_file.read()
# Prepare the multipart form data
files = {
'image': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg'),
'model': (os.path.basename(IMAGE_PATH), model_data, 'application/octet-stream'),
}
# Prepare the data
data = {
'prompt': "prompt reference."
'strength': 5,
'geometry_file_format': 'glb',
'material': 'PBR',
'resolution': 'Basic',
}
# Prepare the headers
headers = {
'Authorization': f'Bearer {API_KEY}',
}
# Make the POST request
response = requests.post(ENDPOINT, data = data, files = files, headers=headers)
# Check if request was successful
if response.status_code == 200:
# Parse and print the JSON response
result = response.json()
print("Success! Task submitted:")
print(f"Task UUID: {result.get('uuid')}")
else:
print(f"Error: {response.status_code}")
print(response.text)
```
{% 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 %}
# Check Balance
{% openapi src="/files/rA0xuGrMtEOsEqeySbPJ" path="/api/v2/check\_balance" method="get" %}
[public-api.json](https://563398440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiMYwiLTHWAzkgBEpY5K%2Fuploads%2Fgit-blob-8b3e8c417bade1e10d0190a05b80cfb0b4f9c3bb%2Fpublic-api.json?alt=media)
{% endopenapi %}
调用该API节点以查询账户剩余余额。
### 收费
调用该API节点以查询账户剩余余额不会收取任何费用。
### 请求
#### Authentication
此API使用密钥进行身份验证。您需要在所有请求的`Authorization`头中包含一个有效的密钥.
```
Authorization: Bearer RODIN_API_KEY
```
### 响应
JSON响应包含以下字段。
| Property | Type | Description |
| -------- | ---- | ------------------- |
| balance | int | Balance of account. |
### Examples
{% tabs %}
{% tab title="Request with cURL" %}
```sh
export RODIN_API_KEY="your api key"
curl --location 'https://api.hyper3d.com/api/v2/check_balance' \
--header 'Authorization: Bearer JWT'
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python3" %}
```python
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/check_balance"
API_KEY = os.getenv("HYPER3D_API_KEY")
# Prepare the headers
headers = {
'Authorization': f'Bearer {API_KEY}',
}
# Make the GET request
response = requests.get(ENDPOINT, headers=headers)
# Parse and return the JSON response
print(response.json())
```
{% endtab %}
{% endtabs %}
# Check Status
检查提交给API的任务的执行状态。
{% openapi src="/files/3NCp1UPfaUcBcGXLFv1I" path="/api/v2/status" method="post" %}
[status.yaml](https://563398440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiMYwiLTHWAzkgBEpY5K%2Fuploads%2Fgit-blob-0d5da29d98dcbc89a802602efd10a8560426dffb%2Fstatus.yaml?alt=media)
{% endopenapi %}
API生成模型消耗资源和时间，因此我们将其设计为异步的。这意味着你提交了一个生成任务后并不一定能立即得到结果。
{% hint style="warning" %}
请不要过于频繁地调用此API，因为它可能会给我们的服务器带来一些额外的压力。我们可能会限制一些发送过于频繁的请求。
{% endhint %}
相反的，您可以在程序中向API端点提供您从[Generation API call](/zh_cn/api-specification/rodin-generation_reset_v)获得的任务的subscription\_key来定期检查您提交的任务的状态。当API提示您的任务已经完成，您就可以使用[Download API](/zh_cn/api-specification/download-results_reset_v)来获取一个Url列表，并在这里下载您的任务生成的模型。
下表列出了API调用中`status`字段中可能出现的值以及他们的含义。
| Status | 含义 |
| ------------ | ----------------------------------------------------------------------------------------- |
| `Waiting` | 您的任务已经进入我们的任务队列，等待执行生成。 |
| `Generating` | 正在为您的任务生成模型。 |
| `Done` | 任务已经完成，现在您可以使用[Download API](/zh_cn/api-specification/download-results_reset_v)来下载您的任务结果。 |
| `Failed` | 任务执行失败，您可能需要联系我们的支持团队以了解详情。 |
## 价格
我们不会对调用API查询任务进度的行为收取任何额外的费用。
## 请求
### Authentication
此API使用密钥进行身份验证。您需要在所有请求的`Authorization`头中包含一个有效的密钥.
```
Authorization: Bearer RODIN_API_KEY
```
### Body
API在`POST`请求体中需求一个参数。
| Parameter | Type | Description |
| --------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| **subscription\_key** | **string** | **Required.** 要查询的任务的subscription\_key，通常您将从[Generation API](/zh_cn/api-specification/rodin-generation_reset_v)的响应中得到它。 |
## 响应
JSON响应包含以下字段。
| Property | Type | Description |
| ----------- | ---------------- | ----------------------------------- |
| error | string | 可选。 可能存在的错误信息。 |
| jobs | array of objects | 任务的作业，包含作为生成过程的一部分执行的各个作业的详细信息。 |
| jobs.uuid | string | 作业的uuid。 |
| jobs.status | string | 作业执行状态。可能的状态请参阅[上表](#api-v2-status) |
## 样例
{% tabs %}
{% tab title="Request with cURL" %}
```sh
export RODIN_API_KEY="your api key"
curl -X 'POST' \
'https://api.hyper3d.com/api/v2/status' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"subscription_key": "your-subscription-key"
}'
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/status"
API_KEY = os.getenv("HYPER3D_API_KEY")
SUBSCRIPTION_KEY = "your-subscription-key" # Replace with your actual subscription key
# Prepare the headers
headers = {
'accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': f'Bearer {API_KEY}',
}
# Prepare the JSON payload
data = {
"subscription_key": SUBSCRIPTION_KEY
}
# Make the POST request
response = requests.post(ENDPOINT, headers=headers, json=data)
# Parse and return the JSON response
print(response.json())
```
{% endtab %}
{% tab title="Request with Go" %}
```go
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
const BaseURI = "https://api.hyper3d.com/api"
type CommonError struct {
Error *string `json:"error,omitempty"`
}
type ApiTaskStatusPair struct {
Uuid string `json:"uuid"`
Status string `json:"status"`
}
type ApiStatusResponse struct {
CommonError
Jobs []ApiTaskStatusPair `json:"jobs"`
}
func CheckStatus(token string, subscriptionKey string) (*ApiStatusResponse, error) {
payload := map[string]string{"subscription_key": subscriptionKey}
jsonData, err := json.Marshal(payload)
if err != nil {
return nil, err
}
req, err := http.NewRequest("POST", fmt.Sprintf("%s/v2/status", BaseURI), bytes.NewBuffer(jsonData))
if err != nil {
return nil, err
}
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var responseData ApiStatusResponse
err = json.NewDecoder(resp.Body).Decode(&responseData)
if err != nil {
return nil, err
}
if responseData.Error != nil {
return nil, fmt.Errorf("error: %s", *responseData.Error)
}
return &responseData, nil
}
func main() {
// Replace with your actual API key
token := "your api key"
// Replace with your subscription key
resp, _ := CheckStatus(token, "your subscription key for a task")
fmt.Println(resp)
}
```
{% endtab %}
{% tab title="Response" %}
```json
{
"jobs": [
"123e4567-e89b-12d3-a456-426614174000": "Generating"
]
}
```
{% endtab %}
{% endtabs %}
# Download Results
下载提交到API的给定任务的结果。
{% openapi src="/files/rA0xuGrMtEOsEqeySbPJ" path="/api/v2/download" method="post" %}
[public-api.json](https://563398440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiMYwiLTHWAzkgBEpY5K%2Fuploads%2Fgit-blob-8b3e8c417bade1e10d0190a05b80cfb0b4f9c3bb%2Fpublic-api.json?alt=media)
{% endopenapi %}
在Check status端点返回的`Done`状态之后，调用这个API端点来获取生成任务的下载url。
{% hint style="info" %}
在任务完成之前调用这个API端点可能会返回错误的结果，比如文件列表不完整。 查看[ Check Status ](/zh_cn/api-specification/check-status_reset_v)了解如何查看任务是否完成。
{% endhint %}
### 价格
我们不会对调用API下载生成结果的行为收取任何额外的费用。
### 请求
#### Authentication
此API使用密钥进行身份验证。您需要在所有请求的`Authorization`头中包含一个有效的密钥. 参
```
Authorization: Bearer RODIN_API_KEY
```
#### Body
API在`POST`请求体中需求一个参数。
{% hint style="info" %}
对于[response from the Generation API](/zh_cn/api-specification/rodin-generation_reset_v#response)的`task_uuid`，使用`uuid`字段替代`jobs_uuid`。
{% endhint %}
| Parameter | Type | Description |
| -------------- | ---------- | ----------------------------------------------- |
| **task\_uuid** | **string** | **Required.** 需要查询状态的任务UUID。通常，您将在生成API的响应中获得它。 |
### 响应
JSON响应包含以下字段。您可以在list列表中下载preview\.webp以预览模型。
| Property | Type | Description |
| --------- | ------ | -------------- |
| error | string | 可选。 可能存在的错误信息。 |
| list | array | 此任务可下载的模型文件列表。 |
| list.url | string | 下载模型文件的URL。 |
| list.name | string | 模型文件的名称。 |
### 样例
{% tabs %}
{% tab title="Request with cURL" %}
```sh
export RODIN_API_KEY="your api key"
curl -X 'POST' \
'https://api.hyper3d.com/api/v2/download' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"task_uuid": "your-task-uuid"
}'
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python3" %}
```python
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/download"
API_KEY = os.getenv("HYPER3D_API_KEY")
TASK_UUID = "your-task-uuid" # Replace with your actual task UUID
# Prepare the headers
headers = {
'accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': f'Bearer {API_KEY}',
}
# Prepare the JSON payload
data = {
"task_uuid": TASK_UUID
}
# Make the POST request
response = requests.post(ENDPOINT, headers=headers, json=data)
# Parse and return the JSON response
print(response.json())
```
{% endtab %}
{% tab title="Response" %}
```json
{
"list": [
{
"url": "https://example.com/",
"name": "testfile"
}
]
}
```
{% endtab %}
{% endtabs %}
# Generate Texture
## 贴图生成
{% openapi src="/files/5w81V2d3ohxMjZNUCiOF" path="/api/v2/rodin\_texture\_only" method="post" %}
[tmp.yaml](https://563398440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiMYwiLTHWAzkgBEpY5K%2Fuploads%2Fgit-blob-74b44ac4fa8f9db435ebd9d2d2be7fc11aca2bbd%2Ftmp.yaml?alt=media)
{% endopenapi %}
## 贴图生成
使用此API向我们的服务器提交异步任务。你将从API中获得一个任务UUID，该UUID可用于[ 检查进度 ](/zh_cn/api-specification/check-status_reset_v)和[ 下载结果 ](/zh_cn/api-specification/download-results_reset_v)。
#### 价格
每次调用该API生成需要消耗 0.5 credits。
#### Request
{% hint style="info" %}
**Note**: 所有到这个端点的请求都必须使用`multipart/form-data`发送，以正确处理文件上传以及网格和纹理生成过程所需的其他参数。
{% endhint %}
**Authentication**
此API使用密钥进行身份验证。您需要在所有请求的`Authorization`头中包含一个有效的密钥. 参阅[快速开始](/zh_cn#authentication-for-rodin-api)获取您的账户的API生成密钥。
```
Authorization: Bearer RODIN_API_KEY
```
**Body**
| 参数 | 类型 | 描述 |
|---|
| image | file/Binary | 必须. 上传一张图片文件作为生成贴图的图片参考。 |
| prompt | string | 可选的。一段描述贴图的文字，指导贴图生成。 |
| model | file/Binary | 必须. 上传一个二进制的三维模型文件进行处理。 |
| seed | number | 可选的。网格生成中用于随机化的种子值，范围从0到65535(包括两者)。如果不提供，种子将随机生成。 |
| reference_scale | number | 可选的。表示纹理生成过程中的参考尺寸。 |
| geometry_file_format | string | 可选的。模型文件的格式。可能的值为glb，usdz，fbx，obj，stl。默认值为glb。 |
| material | string | 可选的。材质类型。可能的值为PBR和Shaded。默认值为PBR。 |
| resolution | string | 可选的。 输出贴图的分辨率。可能的值为Basic 和 High. 默认是Basic. |
#### 样例
{% tabs %}
{% tab title="Request with cURL" %}
```bash
export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/rodin_texture_only \
-H "Authorization: Bearer ${RODIN_API_KEY}" \
-F "image=@/path/to/your/image.jpg" \
-F "model=@path/to/your/model.obj" \
-F "reference_scale=1.0" \
-F "geometry_file_format=glb" \
-F "material=PBR" \
-F "resolution=High"
unset RODIN_API_KEY
```
{% endtab %}
{% tab title="Request with Python 3" %}
```python
import requests
# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/rodin_texture_only"
API_KEY = os.getenv("HYPER3D_API_KEY")
IMAGE_PATH = "/path/to/your/image.jpg" # Replace with the path to your image
MODEL_PATH = "/path/to/your/model.obj"
# Prepare the headers
headers = {
'Authorization': f'Bearer {API_KEY}',
}
# Prepare the form data
files = {
'image': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg'),
'model': (os.path.basename(MODEL_PATH), model_data, 'model/obj'),
'reference_scale': (None, 1.0),
'geometry_file_format': (None, 'glb'),
'material': (None, PBR),
'resolution': (None, 'High'),
}
# Make the POST request
response = requests.post(ENDPOINT, headers=headers, files=files)
# Parse and return the JSON response
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 %}
# Data Policy
在Rodin中，我们优先考虑安全性，并努力工作以维护我们API的完整性。请放心，您的数据和您的用户数据将由我们保护。我们保证您的数据将被安全存储7天，不会用于培训目的，未经您明确同意，不会被共享。此外，使用API生成的模型将不会出现在任何用户的资产选项卡中。