Bang
使用 Rodin asset 或上传的模型提交 Bang 任务。
bearerAuthorizationBearer <token>multipart/form-data- body
asset_id?stringasset_id与model互斥，仅能使用其中一个。
Rodin 生成任务的 uuid。
uuidprompt?string可选，Prompt作为额外的参考，仅能搭配model使用。
image?file参考图片，搭配自定义模型`model`使用，用于指导生成模型贴图。 以下情况此参数必须填写： - 搭配自定义模型`model`使用, 且`material`不为`None`时。 - 搭配自定义模型`model`使用, 且使用`instruction`时。
binarymodel?fileasset_id与model互斥，仅能使用其中一个。将此模型进行bang生成。支持格式有: 'obj', 'glb', 'stl', 'fbx', 'usd'等。
binarystrength?integer可选。控制模型分割的强度。数值越大，分割出的部分越多。
1 <= value <= 125escore?number在asset_id 和自定义模型模式下均可控制纹理的复杂度/丰富度。数值越高，纹理越精细；数值越低，纹理越简洁、平滑。
0 <= value <= 103.5reference_scale?number可选。控制纹理生成在资产ID和自定义模型模式下对参考图像的遵循程度。
0 <= value <= 10.5seed?integer可选。用于指导生成的模型的随机种子。
0 <= value <= 65535geometry_file_format?string可选。用于指导生成的模型的几何文件格式。
"glb""glb""usdz""fbx""obj""stl"material?string可选。生成模型的材质。 - `PBR`：基于物理渲染的材质，包含基础色贴图、金属度贴图、法线贴图和粗糙度贴图。可实现高度真实感，并对动态光照做出物理准确的响应。 - `Shaded`：包含烘焙光照的基础色贴图。 - `All`：同时包含 PBR 和 Shaded 材质。 - `Hybrid`：带有基础颜色纹理的PBR纹理贴图，其中包含烘焙光照。 - `None`：不生成材质；这是上传自定义 `model` 时唯一可以省略 `image` 的取值。
"PBR""PBR""Shaded""All""Hybrid""None"resolution?string可选。用于指导生成模型贴图的分辨率。 - `Basic`: 2K 贴图。 - `High`: 4K 贴图。
"Basic""Basic""High"instruction?string可选。用于指导bang任务的指令。
非空值时会启用bang任务的指令模式，将依据指令对模型进行定向的分件处理。
quality_override?integer可选。指定所有输出部分的最终面数，而非每个部分单独设置。会覆盖源资产的设置。若未指定，无论原始资产的面数如何，都使用Rodin Gen-2 medium quality: 18000（Quad模式）/150000（Raw模式）。注意：原始网格面数仅在超过目标值时才会被简化。Quad模式下，该参数的目标面数上限为50000。
500 <= value <= 2000000mesh_mode?string可选，控制网格拓扑： - `Quad`：四边形网格。 - `Raw`：三角面网格。
"Raw""Quad""Raw"application/json- response
error?string错误码，当请求无法提交时返回。该字段会随 HTTP 201 一起在响应体中返回，因此客户端必须检查此字段，而不能仅依赖 HTTP 状态码。成功时省略此字段。错误码详细请参考 [errors](/zh/api-specification/errors)。
"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成功消息或详细错误信息。
uuid?string提交的生成任务的唯一标识符。
uuidsubmit_time?string提交任务的服务器时间。
date-timejobs?一个包含生成过程中执行的各个任务详细信息的工作对象。
consumed?number本次请求消耗的 credits。
curl -X POST 'https://api.hyper3d.com/api/v2/bang'{ "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 只接受以下两种输入方式之一。同时提交 asset_id 和 model，或两者都不提交，都会被拒绝。
Rodin asset 输入
把已完成的 Rodin 生成响应中的顶层 uuid 作为 asset_id。
- 必填：
asset_id。 - 可选：
geometry_file_format、strength、material、resolution、seed、escore和reference_scale。 - 互斥：必须省略
model、image和prompt。
启用材质生成时，escore 和 reference_scale 对两种输入模式都生效。与 asset_id 一起传入的值会覆盖该 asset 中保存的对应设置；省略时 endpoint 使用请求默认值。
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'
自定义模型输入
上传一个模型。除非 material 为 None，否则参考 image 为必填，因为材质生成需要采样来源；缺少时会返回 INVALID_REQUEST，并在 message 中说明原因。
- 必填：
model；除非material=None，否则还需要image。 - 可选：
geometry_file_format、prompt、strength、material、resolution、reference_scale、escore、seed。 - 互斥：必须省略
asset_id。 - 支持的模型格式：
obj、glb、stl、fbx、usd、usda、usdz和usdc。 strength取值范围为 1 到 12，默认为 5。值越大，模型被拆分出的部件越多。
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'
计费
每个 Bang 请求均扣除 0.5 credits，不受 Rodin asset、自定义上传模型或其他输入选项影响。
响应与错误
{
"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 使用与其他生成 endpoint 相同的应用错误码。HTTP 201 仅表示 endpoint 已处理请求；只有在 error 缺失或为空且顶层 uuid 非空时，任务才算已受理。HTTP 400 表示字段无效、文件不受支持或输入方式冲突；401 表示鉴权无效；429 表示触发限流。状态查询和下载遵循与其他生成接口相同的标识规则。