# Bang!

{% openapi src="<https://3170127470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fve7H9sNOF32Exg6OAhKo%2Fuploads%2Fgit-blob-b8a0f22d84d1f9e7a2e28c0dbdaa8437f08960c9%2FBANG.yaml?alt=media>" 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](https://developer.hyper3d.ai/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**

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.hyper3d.ai/api-specification/bang_reset_v.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.