Loading API documentation
Rig a mesh and optionally attach compatible animation clips.
The client provides a convenient way to interact with the model API.
npm install --save @fal-ai/clientSet FAL_KEY as an environment variable in your runtime.
export FAL_KEY="YOUR_API_KEY"The client API handles the API submit protocol. It will handle the request status updates and return the result when the request is completed.
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);The API uses an API Key for authentication. It is recommended you set the FAL_KEY environment variable in your runtime when possible.
import { fal } from "@fal-ai/client";
fal.config({
credentials: "YOUR_FAL_KEY"
});The client API provides a convenient way to submit requests to the model.
import { fal } from "@fal-ai/client";
const { request_id } = await fal.queue.submit("hyper3d/rigging", {
input: {
model_url: ""
},
webhookUrl: "https://optional.webhook.url/for/results",
});You can fetch the status of a request to check if it is completed or still in progress.
import { fal } from "@fal-ai/client";
const status = await fal.queue.status("hyper3d/rigging", {
requestId: "764cabcf-b745-4b3e-ae38-1200304cf45b",
logs: true,
});Once the request is completed, you can fetch the result. See the Output Schema for the expected result format.
import { fal } from "@fal-ai/client";
const result = await fal.queue.result("hyper3d/rigging", {
requestId: "764cabcf-b745-4b3e-ae38-1200304cf45b"
});
console.log(result.data);
console.log(result.requestId);Some attributes in the API accept file URLs as input. Whenever that's the case you can pass your own URL or a Base64 data URI.
You can pass a Base64 data URI as a file input. The API will handle the file decoding for you. Keep in mind that for large files, this alternative although convenient can impact the request performance.
You can also pass your own URLs as long as they are publicly accessible. Be aware that some hosts might block cross-site requests, rate-limit, or consider the request as a bot.
We provide a convenient file storage that allows you to upload files and use them in your requests. You can upload files using the client API and use the returned URL in your requests.
import { fal } from "@fal-ai/client";
const file = new File(["Hello, World!"], "hello.txt", { type: "text/plain" });
const url = await fal.storage.upload(file);Read more about file handling in our file upload guide.
model_url string* requiredURL 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 BoneTemplateEnumSkeleton 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"
Possible enum values: auto, human, quadruped, bird, dragon, kaiju, custom
image_url stringOptional 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 SkinningMethodEnumshell favors smooth weights on the visible mesh for general use; core concentrates influences around the structure for precise humanoid joints. Default value: "shell"
Possible enum values: shell, core
1–256 bones defining a custom skeleton as a flat list. Requires bone_template=custom; cannot accompany skeleton_description.
skeleton_description stringNonblank text describing anatomy and limbs. Requires bone_template=custom and replaces hierarchy. Uses image_url when provided, otherwise text only.
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.
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.
in_place booleanExport looping stock animations in place. Non-looping clips are unchanged. Cannot be enabled with animation_urls.
geometry_file_format GeometryFileFormatEnumChoose one output format for the rigged mesh: GLB, FBX, or USDZ. Default value: "fbx"
Possible enum values: glb, fbx, usdz
{
"model_url": "",
"bone_template": "auto",
"skinning_method": "shell",
"hierarchy": null,
"animation_presets": [],
"geometry_file_format": "fbx"
}Original rigged model, including all animation clips.
Rigged GLB without animation clips.
One complete GLB per animation clip.
Rigged FBX when the partner returns FBX.
Additional model, skeleton, or animation artifacts.
Output texture images.
{
"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
}
]
}url string* requiredThe URL where the file can be downloaded from.
content_type stringThe mime type of the file.
file_name stringThe name of the file. It will be auto-generated if not provided.
file_size integerThe size of the file in bytes.
action_id string* requiredAnimation clip name from the returned GLB.
Complete rigged character with this clip.
url string* requiredThe URL where the file can be downloaded from.
content_type stringThe mime type of the file.
file_name stringThe name of the file. It will be auto-generated if not provided.
file_size integerThe size of the file in bytes.
width integerThe width of the image in pixels.
height integerThe height of the image in pixels.
name string* requiredBone name.
parent integer* requiredParent node index, or -1 for the root.
Optional flat bone transform in input model coordinates.
length floatBone length along local +Y in input model units. Omit for automatic calculation; explicit null is not accepted.