骨骼绑定
使用骨架模板、自定义层级与可选动画，为 Rodin 资产或上传的模型绑定骨骼。
bearerAuthorizationBearer <token>multipart/form-data- body
bone_template?string可选。骨架模板，省略时默认为 `auto`。 - `auto`：仅用于生成模式；优先根据上传的参考图，否则根据资产的 input/0000 原始输入图，从 human、quadruped、bird、dragon、kaiju 中选择最可能的骨架，即使只能近似匹配。必须有可用图片，且不能提供 `hierarchy` 或 `skeleton_description`。 - 生成模式预设：`human`、`quadruped`、`human_UE`、`human_Unity`、`human_ActorCore`、`bird`、`dragon` 和 `kaiju`；不要提供 `hierarchy` 或 `skeleton_description`。 - 人形变体选择 Unreal Engine、Unity 或 ActorCore 骨架模板。名称区分大小写。 - 生成模式 `custom`：必须且只能提供 `hierarchy` 或 `skeleton_description` 之一。 - 修改模式：显式选择模板，提供 `skeleton_description` 并省略 `hierarchy`。骨架将从描述中解析，而不是加载所选模板。
"auto""human""quadruped""human_UE""human_Unity""human_ActorCore""bird""dragon""kaiju""custom""auto"rigging_mode?string`generate` 沿用现有输入规则。`modify` 接受所选模板，要求 `skeleton_description` 包含完整的基准骨架与所要求的修改，且不提供 `hierarchy`。
"generate""generate""modify"asset_id?string**参数 `asset_id` 与 `model` 互斥，必须且只能提供其一。** 已确认 Rodin 模型的 UUID。
uuidmodel?file**参数 `asset_id` 与 `model` 互斥，必须且只能提供其一。** 用于绑定的模型。支持格式：'obj'、'glb'、'stl'、'fbx'、'usd'、'usda'、'usdz' 和 'usdc'。内嵌的材质与贴图不会被保留。
binaryimage?file为 `model` 或 `asset_id` 提供的参考图，格式为 JPG、PNG 或 WebP。`bone_template=auto` 时，上传图片优先于资产原始输入图，至少需要一种可用图片来源。 与 `skeleton_description` 一起用于理解身体结构，`material=None` 时也是如此。上传 `model` 且 `material` 不为 `None` 时**必填**，因为同一张图也会用于贴图生成。使用 `asset_id` 时复用已确认的贴图。显式选择骨架模板时，省略图像则保持纯文本骨架处理。提供图像并不会启用贴图生成。
binaryskinning_method?string可选。模型的蒙皮方式。 - `shell`：以表面为先，更通用，在可见外层网格上产生更平滑的权重分布。 - `core`：以结构为先，专门针对人形角色优化，影响范围更窄，关节活动更精准。
"shell""shell""core"hierarchy?array<>自定义骨架，以扁平节点列表形式编码为 JSON 数组字符串。仅在生成模式且 `bone_template=custom` 时生效；与 `skeleton_description` 互斥。修改模式下不要提供；请改为在 `skeleton_description` 中包含基准骨架。
1 <= items <= 256skeleton_description?string非空的骨架身体结构与四肢描述。 生成模式下仅与 `bone_template=custom` 一起使用，且与 `hierarchy` 互斥。
\Sanimation_preset?array<>可选。与骨架兼容的不重复内置动画 ID。接受单个 ID、重复字段或 JSON 数组字符串。最多 10 个预设；与 `animation_files` 互斥。两个字段都省略时导出不带动画。
items <= 10animation_files?array<>可选。非空 FBX 动画文件，每个不超过 25 MiB。多个文件请重复此字段。每个文件必须恰好包含一个动画片段（Take）；不支持包含零个或多个片段的文件。最多 10 个文件；与 `animation_preset` 互斥。自定义动画必须与目标骨架匹配。
items <= 10material?string可选。材质类型。对有已确认贴图的资产默认为 `PBR`，否则为 `None`。 - `PBR`：基础色、金属度、法线和粗糙度贴图。 - `Shaded`：带烘焙光照的基础色。 - `Hybrid`：PBR 贴图且基础色中包含烘焙光照。 - `All`：同时输出 PBR 和 Shaded。 - `None`：导出时不带材质。 非 `None` 值要求 `asset_id` 有已确认贴图，或为 `model` 提供 `image` 以生成贴图。
"PBR""Shaded""All""Hybrid""None"geometry_file_format?string可选。绑定后模型的文件格式。选择一种格式。
"glb""glb""fbx""usdz"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新绑定任务的 UUID。每次提交都会创建独立任务。所有任务均为 Done 后，将其作为 `task_uuid` 调用 `POST /api/v2/download` 下载结果。
uuidsubmit_time?string提交任务的服务器时间。
date-timejobs?已提交的任务。用 `subscription_key` 轮询 `POST /api/v2/status`，直到包括打包在内的所有任务变为 Done 后再下载。
consumed?number提交时预扣的 credits。打包成功时扣除；失败或取消时释放。
curl -X POST 'https://api.hyper3d.com/api/v2/rigging'{ "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}Rigging 只接受以下两种输入方式之一。同时提交 asset_id 和 model，或两者都不提交，都会被拒绝。
使用预设骨架生成
将 bone_template 设为预设之一——human、quadruped、human_UE、human_Unity 或 human_Actorcore——不要提供 hierarchy 或 skeleton_description。预设模板支持以下两种输入方式。
Rodin asset 输入
把已完成的 Rodin 生成响应中的顶层 uuid 作为 asset_id。该资产必须在 ModelRefine、TextureGenerate 或 TextureRefine 中已确认模型；不支持 rodin_texture_only 创建的资产。已确认的几何与贴图会被复用且不修改源资产，源输入图像在可用时会自动复用。
- 必填：
asset_id、bone_template。 - 互斥：必须省略
model和image。
curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rigging' \
--header "Authorization: Bearer ${RODIN_API_KEY}" \
--form 'asset_id=123e4567-e89b-12d3-a456-426614174000' \
--form 'bone_template=human' \
--form 'animation_preset=human/Walking' \
--form 'geometry_file_format=fbx'
自定义模型输入
上传一个模型。除非 material 为 None，否则参考 image 为必填，因为贴图生成需要从中采样；该图像还会帮助理解身体结构。
- 必填：
model、bone_template；除非material=None，否则还需要image。 - 互斥：必须省略
asset_id。 - 支持的模型格式：
obj、glb、stl、fbx、usd、usda、usdz和usdc。内嵌的材质与贴图不会被保留。
curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rigging' \
--header "Authorization: Bearer ${RODIN_API_KEY}" \
--form 'model=@./model.glb' \
--form 'image=@./reference.png' \
--form 'bone_template=human' \
--form 'material=PBR' \
--form 'animation_preset=human/Walking' \
--form 'geometry_file_format=glb'
效果展示
使用预设模板的完整绑定流程：从单个上传模型到带动画的绑定输出。
API 请求 — 将人形网格发送到预设 human 骨骼模板，接收带动画的绑定资产。
curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rigging' \
--header "Authorization: Bearer ${RODIN_API_KEY}" \
--form 'model=@./model.fbx' \
--form 'bone_template=human' \
--form 'skinning_method=core' \
--form 'material=None' \
--form 'animation_preset=human/Flair' \
--form 'geometry_file_format=fbx'
动画输出 — 绑定后的网格正在驱动动画。可使用查看器下方的播放/暂停/重置控件，或下载 FBX 到你的 DCC 中检查骨架与动画。
API 请求 — 将四足网格发送到预设 quadruped 骨骼模板，接收带动画的绑定资产。
curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rigging' \
--header "Authorization: Bearer ${RODIN_API_KEY}" \
--form 'model=@./model.fbx' \
--form 'bone_template=quadruped' \
--form 'skinning_method=shell' \
--form 'material=None' \
--form 'animation_preset=canine/Default_Canine_Run_Anim' \
--form 'geometry_file_format=fbx'
动画输出 — 绑定后的网格正在驱动动画。可使用查看器下方的播放/暂停/重置控件，或下载 FBX 到你的 DCC 中检查骨架与动画。
使用自定义骨架生成
设置 bone_template=custom，并且必须且只能提供 hierarchy 或 skeleton_description 之一。两种输入方式（asset_id 或 model）均可；以下示例使用上传模型。
hierarchy
hierarchy 以 JSON 数组字符串编码的扁平节点列表描述骨架。每个节点包含 name、parent（父节点索引）以及可选的 transform 和 length。
请求中以 JSON 数组字符串形式发送：
curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rigging' \
--header "Authorization: Bearer ${RODIN_API_KEY}" \
--form 'model=@./model.glb' \
--form 'image=@./reference.png' \
--form 'bone_template=custom' \
--form 'hierarchy=[{"name":"root","parent":-1},{"name":"spine","parent":0},{"name":"head","parent":1}]' \
--form 'material=PBR' \
--form 'geometry_file_format=glb'
skeleton_description
skeleton_description 是对身体结构与四肢的非空自然语言描述。有可用图像时——上传的 image 或源资产的输入图像——会随描述一起发送；没有图像时保持纯文本处理。
curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rigging' \
--header "Authorization: Bearer ${RODIN_API_KEY}" \
--form 'model=@./model.glb' \
--form 'image=@./reference.png' \
--form 'bone_template=custom' \
--form 'skeleton_description=A quadruped with four legs, a long neck, and a tail.' \
--form 'material=PBR' \
--form 'geometry_file_format=glb'
效果展示
完整的自定义绑定流程：从单个上传模型、自定义骨架层级和动画文件，最终得到带动画的绑定输出。
API 请求 — 将自定义网格、自定义骨架层级与动画文件发送到 custom 骨骼模板，接收带动画的绑定资产。
curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rigging' \
--header "Authorization: Bearer ${RODIN_API_KEY}" \
--form 'model=@./model.fbx' \
--form 'bone_template=custom' \
--form 'skinning_method=shell' \
--form 'material=None' \
--form 'animation_files=@./animation.fbx' \
--form 'geometry_file_format=fbx' \
--form 'hierarchy=@./hierarchy.json'
动画输出 — 绑定后的网格正在驱动一个动画。可使用查看器下方的播放/暂停/重置控件，或下载 FBX 到你的 DCC 中检查骨架与动画。
修改已有骨架
设置 rigging_mode=modify，提供包含完整基准骨架与修改要求的 skeleton_description，并省略 hierarchy。骨架将从描述中解析，而不是加载所选模板。
动画
动画为可选。animation_preset（内置动画 ID）或 animation_files（上传的 FBX 片段，每个不超过 25 MiB，且每个文件恰好一个片段），最多 10 个输入。两个字段都省略时导出不带动画。
计费
基础绑定生成：0.5 credits
响应与错误
{
"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
}
Rigging 使用与其他生成 endpoint 相同的应用错误码。HTTP 201 仅表示 endpoint 已处理请求；只有在 error 缺失或为空且顶层 uuid 非空时，任务才算已受理。HTTP 400 表示字段无效、文件不受支持或输入方式冲突；401 表示鉴权无效；429 表示触发限流。状态查询和下载遵循与其他生成接口相同的标识规则。