> For the complete documentation index, see [llms.txt](https://developer.hyper3d.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.hyper3d.ai/api-specification/bang_reset_v.md).

# 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.md) 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**

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>asset_id</td><td>string</td><td><strong>Parameters <code>asset_id</code> and <code>model</code> are mutually exclusive. Provide only one.</strong><br>UUID of the Rodin Gen-2 Generation Task.</td></tr><tr><td>model</td><td>file</td><td><strong>Parameters <code>asset_id</code> and <code>model</code> are mutually exclusive. Provide only one.</strong><br>The model used for BANG. Supported model formats are 'obj', 'glb', 'stl', 'fbx', 'usd', 'usda', 'usdz', and 'usdc'.</td></tr><tr><td>image</td><td>file</td><td>Optional, Images to be used for reference.<br>The <code>image</code> parameter must be paired with the <code>model</code> parameter.</td></tr><tr><td>prompt</td><td>string</td><td>Optional, Prompt to be used for reference.<br>The <code>prompt</code> parameter must be paired with the <code>model</code> parameter.</td></tr><tr><td>strength</td><td>number</td><td>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.</td></tr><tr><td>geometry_file_format</td><td>string</td><td>Required. File format for the generated geometry files. Supported formats: <code>glb</code>, <code>obj</code>, <code>fbx</code>, <code>stl</code>, <code>usdz</code>. Default: <code>glb</code>.</td></tr><tr><td>material</td><td>string</td><td>Optional. The material type. Possible values are <code>PBR</code>, <code>Shaded</code>, <code>None</code> and <code>All</code>. Default is <code>PBR</code>.<br><code>PBR</code>: Physically Based Materials, including base color texture, metallicness texture, normal texture and roughness texture, providing high realism and physically accurate over dynamic lighting.<br><code>Shaded</code>: Only base color texture with baked lighting, providing stylized visuals.<br><code>None</code>: Asset without material.<br><code>All</code>: Both <code>PBR</code> and <code>Shaded</code> will be delivered.</td></tr><tr><td>resolution</td><td>string</td><td>Optional. The resolution of the generated texture assets. Possible values are <code>Basic</code> and <code>High</code>. Default is <code>Basic</code>.<br><code>Basic</code>: 2K resolution.<br><code>High</code>: 4K resolution.</td></tr></tbody></table>

{% 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/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 %}

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>error</td><td>string</td><td>Error message, if any.</td></tr><tr><td>message</td><td>string</td><td>Success message or detailed error information.</td></tr><tr><td>uuid</td><td>string</td><td>Unique identifier for the generated task.</td></tr><tr><td>jobs</td><td>object</td><td>A job object, containing details of individual jobs executed as part of the generation process.</td></tr><tr><td>jobs.uuids</td><td>array of strings</td><td>UUIDs of the sub-jobs.</td></tr><tr><td>jobs.subscription_key</td><td>string</td><td>Subscription key associated with these jobs.</td></tr></tbody></table>

Possible Errors include:

<table data-full-width="true"><thead><tr><th>Error</th><th>Description</th></tr></thead><tbody><tr><td>NO_ACTIVE_SUBSCRIPTION</td><td>Does not have an active subscription or the subscription of your account already expired.</td></tr><tr><td>SUBSCRIPTION_PLAN_TOO_LOW</td><td>Bussiness subscription is required to use Rodin Bang! API.</td></tr><tr><td>INSUFFICIENT_FUND</td><td>The user‘s account balance is insufficient to complete the requested operation.</td></tr><tr><td>INVALID_REQUEST</td><td>The request is malformed, missing required parameters, or contains invalid values. Check <code>message</code> for additional information.</td></tr><tr><td>USER_NOT_FOUND</td><td>API KEY invalid or user not exist.</td></tr><tr><td>GROUP_NOT_FOUND</td><td>API KEY invalid or group not exist.</td></tr><tr><td>PERMISSION_DENIED</td><td>The authenticated user does not have permission to perform this action.</td></tr><tr><td>UNKNOWN</td><td>An unexpected error occurred. Check <code>message</code> for additional information.</td></tr></tbody></table>

### **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 %}