Bang

POST

/api/v2/bang

Authorization

bearer

headerAuthorizationBearer <token>

Request Body

multipart/form-data

body

asset_id?string

Parameters asset_id and model are mutually exclusive. Provide exactly one.

UUID of a completed Rodin generation task, taken from the top-level uuid of its generation response.

**Parameters asset_id and model are mutually exclusive. Provide exactly one.** UUID of a completed Rodin generation task, taken from the top-level `uuid` of its generation response.

Formatuuid

prompt?string

Optional. Prompt used as additional reference. Only applies together with model.

Optional. Prompt used as additional reference. Only applies together with `model`.

image?file

Optional. Reference image for the custom model task when using model.

Required for the following cases:

Using model when material is not None

Using model when using instruction.

Optional. Reference image for the custom model task when using `model`. Required for the following cases: - Using `model` when `material` is not `None` - Using `model` when using `instruction`.

Formatbinary

model?file

Parameters asset_id and model are mutually exclusive. Provide exactly one.

The model used for BANG. Supported model formats are 'obj', 'glb', 'stl', 'fbx', 'usd', 'usda', 'usdz', and 'usdc'.

**Parameters asset_id and model are mutually exclusive. Provide exactly one.** The model used for BANG. Supported model formats are 'obj', 'glb', 'stl', 'fbx', 'usd', 'usda', 'usdz', and 'usdc'.

Formatbinary

strength?integer

Controls the strength of the splitting of the model. The larger the value, the more pieces there will be.

Range1 <= value <= 12

Default5

escore?number

Controls texture complexity/richness in both asset_id and custom model modes. Higher values encourage more detailed textures; lower values produce cleaner, flatter textures. When an existing asset is used, this request value overrides its stored setting.

Controls texture complexity/richness in both `asset_id` and custom `model` modes. Higher values encourage more detailed textures; lower values produce cleaner, flatter textures. When an existing asset is used, this request value overrides its stored setting.

Range0 <= value <= 10

Default3.5

reference_scale?number

Controls how strongly texture generation follows the reference image in both asset_id and custom model modes. When an existing asset is used, this request value overrides its stored setting.

Controls how strongly texture generation follows the reference image in both `asset_id` and custom `model` modes. When an existing asset is used, this request value overrides its stored setting.

Range0 <= value <= 1

Default0.5

seed?integer

Random seed for generation. Optional; if omitted, a random seed is generated.

Range0 <= value <= 65535

geometry_file_format?string

Optional. File format for the generated geometry files.

Default"glb"

Value in"glb""usdz""fbx""obj""stl"

material?string

Optional. Material type.

PBR: Physically Based Materials, including base color texture, metallicness texture, normal texture and roughness texture, providing high realism and physically accurate response to dynamic lighting.

Shaded: Only base color texture with baked lighting, providing stylized visuals.

All: Both PBR and Shaded will be delivered.

Hybrid: PBR texture maps with a base color texture that includes baked lighting.

None: Asset without material. This will speed up generation.

Optional. Material type. - `PBR`: Physically Based Materials, including base color texture, metallicness texture, normal texture and roughness texture, providing high realism and physically accurate response to dynamic lighting. - `Shaded`: Only base color texture with baked lighting, providing stylized visuals. - `All`: Both PBR and Shaded will be delivered. - `Hybrid`: PBR texture maps with a base color texture that includes baked lighting. - `None`: Asset without material. This will speed up generation.

Default"PBR"

Value in"PBR""Shaded""All""Hybrid""None"

resolution?string

Optional. Texture generation resolution.

Basic: means 2K texture;

High: means 4K texture.

Optional. Texture generation resolution. - `Basic`: means 2K texture; - `High`: means 4K texture.

Default"Basic"

Value in"Basic""High"

instruction?string

Optional. Instruction for the bang task.

Non-empty value will enable the instruction mode, and the model will be split based on the instruction.

Optional. Instruction for the bang task. Non-empty value will enable the instruction mode, and the model will be split based on the instruction.

quality_override?integer

Optional. Target face count across all output parts, not per part. Overrides the source asset setting. When omitted, uses Rodin Gen-2 medium quality: 18000 for Quad and 150000 for Raw, regardless of the source asset. Raw meshes are only simplified when above the target. In Quad mode, the worker caps the target at 50000 faces.

Range500 <= value <= 2000000

mesh_mode?string

Optional. Control the mesh topology.

Quad：Quad faces mesh.

Raw：Triangle faces mesh.

Optional. Control the mesh topology. - `Quad`：Quad faces mesh. - `Raw`：Triangle faces mesh.

Default"Raw"

Value in"Quad""Raw"

Response Body

application/json

response

error?string

Error code, if the request could not be submitted. This is returned in the response body alongside HTTP 201, so clients must check this field rather than relying on the HTTP status alone. This field is omitted on success. For detailed error code information, please refer to: errors

Value in"NO_SUCH_TASK""ASSET_NOT_AVAILABLE""IMAGE_LABEL_LENGTH_TOO_LONG""INVALID_REQUEST""API_NO_ACTIVE_SUBSCRIPTION""API_SUBSCRIPTION_PLAN_TOO_LOW""API_PARALLELISM_LIMIT_REACHED""API_INSUFFICIENT_FUNDS""API_OBJECT_NOT_FOUND_ON_IMAGE""IMAGE_CONTENT_VIOLATION""PERMISSION_DENIED""API_UNKNOWN"

message?string

Success message or detailed error information.

uuid?string

Unique identifier for the submitted generation task.

Formatuuid

submit_time?string

Server time when the task was submitted.

Formatdate-time

jobs?

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

consumed?number

Credits consumed by this request.

Example Request

curl -X POST 'https://api.hyper3d.com/api/v2/bang'

Example ResponseSchema

{  "error": "NO_SUCH_TASK",  "message": "Submitted.",  "uuid": "123e4567-e89b-12d3-a456-426614174000",  "submit_time": "2019-08-24T14:15:22Z",  "jobs": {    "uuids": [      "52faea01-729e-4195-85e8-6050a65315e3"    ],    "subscription_key": "string"  },  "consumed": 0.5}

Bang accepts exactly one of two input modes. Sending both asset_id and model, or neither, is rejected.

Rodin asset input

Use the top-level uuid returned by a completed Rodin generation as asset_id.

Required: asset_id.
Optional: geometry_file_format, strength, material, resolution, seed, escore, and reference_scale.
Mutually exclusive: model, image and prompt must be omitted.

When material generation is enabled, escore and reference_scale apply in both input modes. Values sent with an asset_id override the corresponding settings stored on that asset; when omitted, the endpoint uses its request defaults.

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/bang' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'asset_id=123e4567-e89b-12d3-a456-426614174000' \
  --form 'strength=5' \
  --form 'geometry_file_format=glb'

Custom model input

Upload one model. A reference image is required unless material is None, because material generation needs something to sample from; omitting it is rejected with INVALID_REQUEST and a descriptive message.

Required: model, and image unless material=None.
Optional: geometry_file_format, prompt, strength, material, resolution, reference_scale, escore, seed.
Mutually exclusive: asset_id must be omitted.
Supported model formats: obj, glb, stl, fbx, usd, usda, usdz, and usdc.
strength accepts 1 to 12 and defaults to 5. Higher values split the model into more pieces.

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/bang' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'model=@./model.glb' \
  --form 'image=@./reference.png' \
  --form 'prompt=Separate the main structural parts' \
  --form 'strength=5' \
  --form 'geometry_file_format=glb'

Pricing

Every Bang request costs 0.5 credits, regardless of whether it uses a Rodin asset or an uploaded custom model and regardless of the selected input options.

Response and errors

{
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
    "uuids": ["223e4567-e89b-12d3-a456-426614174000"],
    "subscription_key": "subscription-key-from-generation-response"
  },
  "consumed": 0.5
}

Bang uses the same application error codes as the other generation endpoints. HTTP 201 means the endpoint handled the request, but the task is accepted only when error is absent or empty and the top-level uuid is non-empty. HTTP 400 covers invalid fields, unsupported files, or conflicting input modes; 401 indicates invalid authentication; 429 indicates throttling. Poll and download using the same identifier rules as other generation endpoints.

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Rodin asset inputCopy Anchor Link

Custom model inputCopy Anchor Link

PricingCopy Anchor Link