Hyper3DHyper3D Docs
API 规范

Bang

使用 Rodin asset 或上传的模型提交 Bang 任务。

POST
/api/v2/bang

使用 Rodin asset_id 或上传的自定义模型提交 Bang 任务，两种输入方式互斥。

Authorization

bearer
AuthorizationBearer <token>

In: header

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.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'

import os

import requests

response = requests.post(
    "https://api.hyper3d.com/api/v2/bang",
    headers={"Authorization": f"Bearer {os.environ['RODIN_API_KEY']}"},
    data={
        "asset_id": "123e4567-e89b-12d3-a456-426614174000",
        "strength": 5,
        "geometry_file_format": "glb",
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

自定义模型输入

上传一个模型。除非 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'

import os
from pathlib import Path

import requests

with Path("model.glb").open("rb") as model_file, Path("reference.png").open("rb") as image_file:
    response = requests.post(
        "https://api.hyper3d.com/api/v2/bang",
        headers={"Authorization": f"Bearer {os.environ['RODIN_API_KEY']}"},
        files={
            "model": ("model.glb", model_file, "model/gltf-binary"),
            "image": ("reference.png", image_file, "image/png"),
        },
        data={
            "prompt": "Separate the main structural parts",
            "strength": 5,
            "geometry_file_format": "glb",
        },
        timeout=60,
    )
response.raise_for_status()
print(response.json())

计费

每个 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 表示触发限流。状态查询和下载遵循与其他生成接口相同的标识规则。

Rodin Gen-1/1.5

使用 Rodin Gen-1/1.5 tier 生成 3D asset。

生成纹理

为上传的 3D 模型生成纹理。