Rigging

POST

/api/v2/rigging

Authorization

bearer

headerAuthorizationBearer <token>

Request Body

multipart/form-data

body

bone_template?string

Optional. Skeleton template. Defaults to auto when omitted.

auto: generate mode only; select the most likely of human, quadruped, bird, dragon, or kaiju from the uploaded image, or the asset input/0000 image, even when the fit is approximate. Requires a usable image and no hierarchy or skeleton_description.

Generate presets: human, quadruped, human_UE, human_Unity, human_ActorCore, bird, dragon, and kaiju; do not provide hierarchy or skeleton_description.

Human variants select the Unreal Engine, Unity, or ActorCore skeleton template. Names are case-sensitive.

Generate custom: provide exactly one of hierarchy or skeleton_description.

Modify: keep the selected template, provide skeleton_description, and omit hierarchy. The skeleton is resolved from the description instead of loading the selected template.

Optional. Skeleton template. Defaults to `auto` when omitted. - `auto`: generate mode only; select the most likely of human, quadruped, bird, dragon, or kaiju from the uploaded image, or the asset input/0000 image, even when the fit is approximate. Requires a usable image and no hierarchy or skeleton_description. - Generate presets: `human`, `quadruped`, `human_UE`, `human_Unity`, `human_ActorCore`, `bird`, `dragon`, and `kaiju`; do not provide `hierarchy` or `skeleton_description`. - Human variants select the Unreal Engine, Unity, or ActorCore skeleton template. Names are case-sensitive. - Generate `custom`: provide exactly one of `hierarchy` or `skeleton_description`. - Modify: keep the selected template, provide `skeleton_description`, and omit `hierarchy`. The skeleton is resolved from the description instead of loading the selected template.

Default"auto"

Value in"human""quadruped""human_UE""human_Unity""human_ActorCore""bird""dragon""kaiju""custom""auto"

rigging_mode?string

generate preserves the existing input rules. modify accepts the selected template and requires skeleton_description containing the complete baseline skeleton and requested changes, without hierarchy.

Default"generate"

Value in"generate""modify"

asset_id?string

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

The UUID of the confirmed Rodin model.

**Parameters asset_id and model are mutually exclusive. Provide exactly one.** The UUID of the confirmed Rodin model.

Formatuuid

model?file

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

The model used for rigging. Supported formats are 'obj', 'glb', 'stl', 'fbx', 'usd', 'usda', 'usdz', and 'usdc'. Embedded materials and textures are not preserved.

**Parameters asset_id and model are mutually exclusive. Provide exactly one.** The model used for rigging. Supported formats are 'obj', 'glb', 'stl', 'fbx', 'usd', 'usda', 'usdz', and 'usdc'. Embedded materials and textures are not preserved.

Formatbinary

image?file

Reference image in JPG, PNG, or WebP format for model or asset_id. For bone_template=auto, an uploaded image takes priority over the asset input image. At least one image source is required. Used together with skeleton_description to understand the body structure, including when material=None. Required for an uploaded model when material is not None, because the same image is also used for texture generation. With asset_id, confirmed textures are reused. For explicit templates, omitting the image preserves text-only skeleton processing. Providing an image does not enable texture generation.

Reference image in JPG, PNG, or WebP format for `model` or `asset_id`. For `bone_template=auto`, an uploaded image takes priority over the asset input image. At least one image source is required. Used together with `skeleton_description` to understand the body structure, including when `material=None`. **Required** for an uploaded model when `material` is not `None`, because the same image is also used for texture generation. With `asset_id`, confirmed textures are reused. For explicit templates, omitting the image preserves text-only skeleton processing. Providing an image does not enable texture generation.

Formatbinary

skinning_method?string

Optional. Skinning method for the model.

shell: Surface-prioritized and more general-purpose, producing smoother weight distributions on the visible outer mesh.

core: Structure-prioritized and specifically optimized for humanoid characters, using a narrower influence scope for more precise articulation.

Optional. Skinning method for the model. - `shell`: Surface-prioritized and more general-purpose, producing smoother weight distributions on the visible outer mesh. - `core`: Structure-prioritized and specifically optimized for humanoid characters, using a narrower influence scope for more precise articulation.

Default"shell"

Value in"shell""core"

hierarchy?array<>

Custom skeleton as a flat node list, encoded as a JSON array string. Only applies in generate mode with bone_template=custom; mutually exclusive with skeleton_description. Do not provide in modify mode; include the baseline skeleton in skeleton_description instead.

Custom skeleton as a flat node list, encoded as a JSON array string. Only applies in generate mode with `bone_template=custom`; mutually exclusive with `skeleton_description`. Do not provide in modify mode; include the baseline skeleton in `skeleton_description` instead.

Items1 <= items <= 256

skeleton_description?string

Non-blank description of the skeleton body structure and limbs.

In generate mode, only applies with bone_template=custom and is mutually exclusive with hierarchy.

Non-blank description of the skeleton body structure and limbs. In generate mode, only applies with `bone_template=custom` and is mutually exclusive with `hierarchy`.

Match\S

animation_preset?array<>

Optional. Distinct stock animation IDs compatible with the skeleton. Accepts one ID, repeated fields, or a JSON array string. Up to 10 presets; mutually exclusive with animation_files. Omit both fields to export without animations.

Optional. Distinct stock animation IDs compatible with the skeleton. Accepts one ID, repeated fields, or a JSON array string. Up to 10 presets; mutually exclusive with `animation_files`. Omit both fields to export without animations.

Itemsitems <= 10

animation_files?array<>

Optional. Non-empty FBX animation files, up to 25 MiB each. Repeat this field for multiple files. Each file must contain exactly one animation clip (Take); files with zero or multiple clips are not supported. Up to 10 files; mutually exclusive with animation_preset. Custom animations must match the target rig.

Optional. Non-empty FBX animation files, up to 25 MiB each. Repeat this field for multiple files. Each file must contain exactly one animation clip (Take); files with zero or multiple clips are not supported. Up to 10 files; mutually exclusive with `animation_preset`. Custom animations must match the target rig.

Itemsitems <= 10

material?string

Optional. Material type. Defaults to PBR for assets with confirmed textures, otherwise None.

PBR: Base color, metallic, normal, and roughness maps.

Shaded: Base color with baked lighting.

Hybrid: PBR maps with baked lighting in the base color.

All: Both PBR and Shaded.

None: Export without materials.

Non-None values require confirmed textures for asset_id, or an image to generate textures for model.

Optional. Material type. Defaults to `PBR` for assets with confirmed textures, otherwise `None`. - `PBR`: Base color, metallic, normal, and roughness maps. - `Shaded`: Base color with baked lighting. - `Hybrid`: PBR maps with baked lighting in the base color. - `All`: Both PBR and Shaded. - `None`: Export without materials. Non-None values require confirmed textures for `asset_id`, or an `image` to generate textures for `model`.

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

geometry_file_format?string

Optional. File format for the rigged model. Select one format.

Default"glb"

Value in"glb""fbx""usdz"

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

UUID of the new rigging task. Each submission creates a separate task. Use as task_uuid with POST /api/v2/download after all jobs are Done.

UUID of the new rigging task. Each submission creates a separate task. Use as `task_uuid` with `POST /api/v2/download` after all jobs are Done.

Formatuuid

submit_time?string

Server time when the task was submitted.

Formatdate-time

jobs?

Submitted jobs. Poll POST /api/v2/status with subscription_key until all jobs, including packaging, are Done before downloading.

Submitted jobs. Poll `POST /api/v2/status` with `subscription_key` until all jobs, including packaging, are Done before downloading.

consumed?number

Credits reserved at submission. Charged on successful packaging; released on failure or cancellation.

Example Request

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

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}

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

Generate with a preset skeleton

Set bone_template to a preset — human, quadruped, human_UE, human_Unity, or human_Actorcore — and do not provide hierarchy or skeleton_description. Presets accept either input mode.

Rodin asset input

Use the top-level uuid returned by a completed Rodin generation as asset_id. The asset must have a confirmed model from ModelRefine, TextureGenerate, or TextureRefine; assets created by rodin_texture_only are not supported. Confirmed geometry and textures are reused without modifying the source, and the source input image is reused automatically when available.

Required: asset_id, bone_template.
Mutually exclusive: model, image must be omitted.

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'

Custom model input

Upload one model. A reference image is required unless material is None, because texture generation samples from it; the same image also helps interpret the body structure.

Required: model, bone_template, and image unless material=None.
Mutually exclusive: asset_id must be omitted.
Supported model formats: obj, glb, stl, fbx, usd, usda, usdz, and usdc. Embedded materials and textures are not preserved.

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'

Showcase

A full preset-template rigging flow, from a single uploaded model to an animated rigged output.

API request — send a humanoid mesh to the preset human bone template and receive a rigged asset with an animation.

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'

Animated output — the rigged mesh driving an animation. Play / pause / reset below the viewer, or download the FBX to inspect the skeleton and animation in your DCC.

API request — send a quadruped mesh to the preset quadruped bone template and receive a rigged asset with an animation.

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'

Animated output — the rigged mesh driving an animation. Play / pause / reset below the viewer, or download the FBX to inspect the skeleton and animation in your DCC.

Generate with a custom skeleton

Set bone_template=custom and provide exactly one of hierarchy or skeleton_description. Either input mode (asset_id or model) works; the examples below upload a model.

hierarchy

hierarchy describes the skeleton as a flat node list encoded as a JSON array string. Each node carries name, parent (the index of the parent node), and optional transform and length.

Send it as a JSON array string in the request:

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 is a non-blank, natural-language description of the body structure and limbs. An image — uploaded as image or reused from the source asset — is sent alongside the description when available; without one, processing remains text-only.

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'

Showcase

A full custom rigging flow, from a single uploaded model, custom skeleton hierarchy and animation file to an animated rigged output.

API request — send a custom mesh, custom skeleton hierarchy and animation file to the custom bone template and receive a rigged asset with an animation.

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'

Animated output — the rigged mesh driving an animation. Play / pause / reset below the viewer, or download the FBX to inspect the skeleton and animation in your DCC.

Modify an existing skeleton

Set rigging_mode=modify and provide skeleton_description containing the complete baseline skeleton and the requested changes; omit hierarchy. The skeleton is resolved from the description instead of loading the selected template.

Animations

Animations are optional. Up to 10 inputs in total from animation_preset (stock animation IDs) or animation_files (uploaded FBX clips, up to 25 MiB each, exactly one clip per file). Omit both fields to export without animations.

Pricing

Base Rigging generation: 0.5 credits

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
}

Rigging 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.

Rigging

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Generate with a preset skeletonCopy Anchor Link

Rodin asset inputCopy Anchor Link

Custom model inputCopy Anchor Link

ShowcaseCopy Anchor Link

Generate with a custom skeletonCopy Anchor Link

hierarchyCopy Anchor Link

Example: complete humanoid hierarchy

skeleton_descriptionCopy Anchor Link

ShowcaseCopy Anchor Link

Modify an existing skeletonCopy Anchor Link

AnimationsCopy Anchor Link

PricingCopy Anchor Link

Response and errorsCopy Anchor Link

Authorization

Request Body

Response Body

Generate with a preset skeleton

Rodin asset input

Custom model input

Showcase

Generate with a custom skeleton

hierarchy

skeleton_description

Showcase

Modify an existing skeleton

Animations

Pricing

Response and errors