# 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.md)分割为多个子模型。 **注意**：此节点只能使用由**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.md)和[下载结果](/zh_cn/api-specification/download-results_reset_v.md)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 %} --- # 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/zh_cn/api-specification/bang_reset_v.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.