Bang!

The all in one API for generating Rodin.

post

The API for Bang a Rodin-generated Asset.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

asset_idstringOptional

modelfileOptional

imagefileOptional

promptstringOptional

strengthnumberOptionalDefault: 5

geometry_file_formatstring · enumOptionalDefault: glbPossible values:

materialstring · enumOptionalDefault: PBRPossible values:

resolutionstring · enumOptionalDefault: BasicPossible values:

Responses

201Success

application/json

post

/api/v2/bang

CLI

curl https://api.hyper3d.com/api/v2/bang \
--request POST \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: multipart/form-data' \
--file 'asset_id=YOUR_UUID' \
--file 'image=@"YOUR_IMAGE"' \
--file 'model=@"YOUR_MODEL"' \
--file 'prompt="prompt"' \
--file "strength=5" \ 
--file "geometry_file_format=glb" \
--file "material=PBR" \
--file "resolution=Basic" \
...

201Success

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

Rodin BANG!

Use this API to split a Rodin-generated Asset into multiple submodels.

Note: Only the models generated by Rodin Gen-2 can be used at this node.

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

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.
- Invalid parameters:
  asset_id must be left empty.
- Optional Parameters (for Texture Generation):
  image: Provide a reference image for generating model textures.
  prompt: Provide a reference prompt for generating model textures.
  Note: If neither image nor prompt is provided, the API will only perform model segmentation and generate a bang model without creating new textures.

Response

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

Property

Type

Description

error

string

Error message, if any.

message

string

Success message or detailed error information.

uuid

string

Unique identifier for the generated task.

jobs

object

A job object, containing details of individual jobs executed as part of the generation process.

jobs.uuids

array of strings

UUIDs of the sub-jobs.

jobs.subscription_key

string

Subscription key associated with these jobs.

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

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

import os
import requests

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

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

Custom Model Bang! Examples

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

import os
import requests

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

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

PreviousGen-1&1.5 Generation NextCheck Balance

Last updated 8 days ago

Was this helpful?

hashtagThe all in one API for generating Rodin.

hashtagRodin BANG!

hashtagPricing

hashtagRequest

hashtagAuthentication

hashtagBody

hashtagResponse

hashtagRodin Task Bang! Examples

hashtagCustom Model Bang! Examples

The all in one API for generating Rodin.

Rodin BANG!

Pricing

Request

Authentication

Body

Response

Rodin Task Bang! Examples

Custom Model Bang! Examples