# Hyper3D Rigging

> Hyper3D Rigging automatically rigs existing 3D models with a skeleton for animation.


## Overview

- **Endpoint**: `https://fal.run/hyper3d/rigging`
- **Model ID**: `hyper3d/rigging`
- **Category**: 3d-to-3d
- **Kind**: inference
**Tags**: 3d, rigging, skeleton, character



## Pricing

Your request will cost $0.2 per request.

For more details, see [fal.ai pricing](https://fal.ai/pricing).

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
See the input and output schema below, as well as the usage examples.


### Input Schema

The API accepts the following input parameters:


- **`model_url`** (`string`, _required_):
  URL of a self-contained mesh with embedded resources: OBJ, GLB, STL, FBX, USD, USDA, USDZ, or USDC. Geometry, embedded materials, and textures are preserved without remeshing or texture generation. **Important**: Before uploading, ensure the model uses a right-handed coordinate system with +Y up and +Z forward (the direction the character faces); +X points to the character's own left. Rigging centers and uniformly scales the model, but does not automatically rotate it to face forward. Correct the orientation before exporting and uploading.

- **`bone_template`** (`BoneTemplateEnum`, _optional_):
  Skeleton template. auto selects human, quadruped, bird, dragon, or kaiju using image_url or a rendered model preview when no image is supplied. Presets forbid hierarchy and skeleton_description; custom requires exactly one. Default value: `"auto"`
  - Default: `"auto"`
  - Options: `"auto"`, `"human"`, `"quadruped"`, `"bird"`, `"dragon"`, `"kaiju"`, `"custom"`
  - Examples: "auto"

- **`image_url`** (`string`, _optional_):
  Optional JPG, PNG, or WebP reference guiding automatic template selection and skeleton_description. If omitted, auto renders a model preview and skeleton_description is processed as text only. Does not trigger texture generation.

- **`skinning_method`** (`SkinningMethodEnum`, _optional_):
  shell favors smooth weights on the visible mesh for general use; core concentrates influences around the structure for precise humanoid joints. Default value: `"shell"`
  - Default: `"shell"`
  - Options: `"shell"`, `"core"`

- **`hierarchy`** (`list<RigHierarchyNode>`, _optional_):
  1–256 bones defining a custom skeleton as a flat list. Requires bone_template=custom; cannot accompany skeleton_description.
  - Array of RigHierarchyNode
  - Examples: null

- **`skeleton_description`** (`string`, _optional_):
  Nonblank text describing anatomy and limbs. Requires bone_template=custom and replaces hierarchy. Uses image_url when provided, otherwise text only.

- **`animation_presets`** (`list<string>`, _optional_):
  Up to 10 distinct stock animation IDs compatible with the skeleton. Use /rigging/animations to look up IDs, names, descriptions, and loop information. Mutually exclusive with animation_urls; leave both empty for an unanimated export.
  - Array of string
  - Examples: []

- **`animation_urls`** (`list<string>`, _optional_):
  Up to 10 FBX URLs matching this rig, each nonempty, at most 25 MiB, and containing exactly one Take. Mutually exclusive with animation_presets; leave both empty for an unanimated export.
  - Array of string

- **`in_place`** (`boolean`, _optional_):
  Export looping stock animations in place. Non-looping clips are unchanged. Cannot be enabled with animation_urls.
  - Default: `false`

- **`geometry_file_format`** (`GeometryFileFormatEnum`, _optional_):
  Choose one output format for the rigged mesh: GLB, FBX, or USDZ. Default value: `"fbx"`
  - Default: `"fbx"`
  - Options: `"glb"`, `"fbx"`, `"usdz"`



**Required Parameters Example**:

```json
{
  "model_url": ""
}
```

**Full Example**:

```json
{
  "model_url": "",
  "bone_template": "auto",
  "skinning_method": "shell",
  "hierarchy": null,
  "animation_presets": [],
  "geometry_file_format": "fbx"
}
```


### Output Schema

The API returns the following output format:

- **`model_mesh`** (`File`, _required_):
  Original rigged model, including all animation clips.

- **`rigged_character_glb`** (`File`, _optional_):
  Rigged GLB without animation clips.

- **`animations`** (`list<RiggingAnimationOutput>`, _optional_):
  One complete GLB per animation clip.
  - Array of RiggingAnimationOutput

- **`fbx_file`** (`File`, _optional_):
  Rigged FBX when the partner returns FBX.

- **`additional_files`** (`list<File>`, _optional_):
  Additional model, skeleton, or animation artifacts.
  - Array of File

- **`textures`** (`list<Image>`, _optional_):
  Output texture images.
  - Array of Image



**Example Response**:

```json
{
  "model_mesh": {
    "url": "",
    "content_type": "image/png",
    "file_name": "z9RV14K95DvU.png",
    "file_size": 4404019
  },
  "animations": [
    {
      "action_id": "",
      "animation_glb": {
        "url": "",
        "content_type": "image/png",
        "file_name": "z9RV14K95DvU.png",
        "file_size": 4404019
      }
    }
  ],
  "additional_files": [
    {
      "url": "",
      "content_type": "image/png",
      "file_name": "z9RV14K95DvU.png",
      "file_size": 4404019
    }
  ],
  "textures": [
    {
      "url": "",
      "content_type": "image/png",
      "file_name": "z9RV14K95DvU.png",
      "file_size": 4404019,
      "width": 1024,
      "height": 1024
    }
  ]
}
```


## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://fal.run/hyper3d/rigging \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
     "model_url": ""
   }'
```

### Python

Ensure you have the Python client installed:

```bash
pip install fal-client
```

Then use the API client to make requests:

```python
import fal_client

def on_queue_update(update):
    if isinstance(update, fal_client.InProgress):
        for log in update.logs:
           print(log["message"])

result = fal_client.subscribe(
    "hyper3d/rigging",
    arguments={
        "model_url": ""
    },
    with_logs=True,
    on_queue_update=on_queue_update,
)
print(result)
```

### JavaScript

Ensure you have the JavaScript client installed:

```bash
npm install --save @fal-ai/client
```

Then use the API client to make requests:

```javascript
import { fal } from "@fal-ai/client";

const result = await fal.subscribe("hyper3d/rigging", {
  input: {
    model_url: ""
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});
console.log(result.data);
console.log(result.requestId);
```


## Deploy your own model

To run your own weights, a fine-tune or a custom pipeline on the GPUs that serve this API, deploy it on fal Serverless. GPUs from H100 (80GB) to B300 (288GB), billed per second; an H100 is $4.50/h list, as low as $2.49/h. Prices, GPU specs and deploy steps: [fal Serverless](https://fal.ai/serverless.md).

## Additional Resources

### Documentation

- [Model Playground](https://fal.ai/models/hyper3d/rigging)
- [API Documentation](https://fal.ai/models/hyper3d/rigging/api)
- [OpenAPI Schema](https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=hyper3d/rigging)

### fal.ai Platform

- [Platform Documentation](https://fal.ai/docs/documentation)
- [Python Client](https://fal.ai/docs/api-reference/client-libraries/python)
- [JavaScript Client](https://fal.ai/docs/api-reference/client-libraries/javascript)

### Other agent-readable surfaces

This file covers one model. To find anything else:

- [Platform overview](https://fal.ai/llms.txt): Entry points and representative endpoint IDs
- [Documentation index](https://fal.ai/docs/llms.txt): Every documentation page
- [Full documentation text](https://fal.ai/docs/llms-full.txt): The whole documentation inlined
- [Pricing](https://fal.ai/pricing.md): Model API and Serverless GPU prices
- [fal Serverless](https://fal.ai/serverless.md): Deploy your own models: GPU prices, specs and steps
- Any other model: `https://fal.ai/models/<endpoint-id>/llms.txt`