> 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/zh_cn/api-specification/bang_reset_v.md). # 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 %}