Loading API documentation
Reconstruct 3D human meshes from an image.
The client provides a convenient way to interact with the model API.
npm install --save @fal-ai/clientThe @fal-ai/serverless-client package has been deprecated in favor of @fal-ai/client. Install the new package and update your imports — see client setup.
Set 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("fal-ai/sam-3/3d-body", {
input: {
image_url: "https://v3b.fal.media/files/b/0a8439f8/E8gEXWsl2C-Euo4dGayzi_An_zyCCnSaytVklh_99sSYt4Z4Hh5e3s7VnNlx5JfN5KuC0j_bnq1AP9JfRoAmOQz5TP0DdCYMk4796Gloe5no1vvpoqhD-p3kE.jpeg"
},
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"
});When running code on the client-side (e.g. in a browser, mobile app or GUI applications), make sure to not expose your FAL_KEY. Instead, use a server-side proxy to make requests to the API. For more information, check out our server-side integration guide.
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("fal-ai/sam-3/3d-body", {
input: {
image_url: "https://v3b.fal.media/files/b/0a8439f8/E8gEXWsl2C-Euo4dGayzi_An_zyCCnSaytVklh_99sSYt4Z4Hh5e3s7VnNlx5JfN5KuC0j_bnq1AP9JfRoAmOQz5TP0DdCYMk4796Gloe5no1vvpoqhD-p3kE.jpeg"
},
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("fal-ai/sam-3/3d-body", {
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("fal-ai/sam-3/3d-body", {
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);The client will auto-upload the file for you if you pass a binary object (e.g. File, Data).
Read more about file handling in our file upload guide.
image_url string* requiredURL of the image containing humans
mask_url stringOptional URL of a binary mask image (white=person, black=background). When provided, skips auto human detection and uses this mask instead. Bbox is auto-computed from the mask.
export_meshes booleanExport individual mesh files (.ply) per person Default value: true
include_3d_keypoints booleanInclude 3D keypoint markers (spheres) in the GLB mesh for visualization Default value: true
include_mhr_params booleanInclude the full MHR (Meta Human Representation) parameter set per person in the response metadata (shape, pose, expression, global rotations, joint coordinates, packed model params, raw pose). Set to false to return a leaner metadata block with only keypoints and camera parameters. Default value: true
{
"image_url": "https://v3b.fal.media/files/b/0a8439f8/E8gEXWsl2C-Euo4dGayzi_An_zyCCnSaytVklh_99sSYt4Z4Hh5e3s7VnNlx5JfN5KuC0j_bnq1AP9JfRoAmOQz5TP0DdCYMk4796Gloe5no1vvpoqhD-p3kE.jpeg",
"export_meshes": true,
"include_3d_keypoints": true,
"include_mhr_params": true
}3D body mesh in GLB format with optional 3D keypoint markers
Combined visualization image (original + keypoints + mesh + side view)
Individual mesh files (.ply), one per detected person (when export_meshes=True)
Structured metadata including keypoints and camera parameters
{
"model_glb": "https://v3b.fal.media/files/b/0a8439f9/5LVt3C2YesqnQzg-CxPpu_combined_bodies.glb",
"visualization": {
"url": "",
"content_type": "image/png",
"file_name": "z9RV14K95DvU.png",
"file_size": 4404019
},
"meshes": [
{
"url": "",
"content_type": "image/png",
"file_name": "z9RV14K95DvU.png",
"file_size": 4404019
}
],
"metadata": {
"people": [
{}
]
}
}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.
num_people integer* requiredNumber of people detected
Per-person metadata
Ordered names of the 70 MHR keypoints returned by this endpoint. Index i in this list corresponds to index i in every person's keypoints_2d and keypoints_3d arrays. Sourced from facebookresearch/sam-3d-body mhr70.py.
person_id integer* requiredIndex of the person in the scene
Bounding box [x_min, y_min, x_max, y_max]
focal_length float* requiredEstimated focal length
Predicted camera translation [tx, ty, tz]
2D keypoints [[x, y], ...] - 70 MHR body keypoints in image coordinates. See SAM3DBodyMetadata.keypoint_names for the ordered name of each index.
3D keypoints [[x, y, z], ...] - 70 MHR body keypoints in camera space. Ordering matches keypoints_2d / SAM3DBodyMetadata.keypoint_names.
MHR identity (β) shape parameters. Enables local canonical-pose mesh reconstruction when combined with the MHR model.
Per-joint body pose parameters (axis-angle form) from the MHR model.
Per-joint hand pose parameters (axis-angle form) from the MHR model.
Global root rotation produced by MHR. Shape matches the upstream tensor (axis-angle [3] or rotation matrix [3, 3]).
Per-joint global rotations (world-space), typically [N_joints, 3, 3] rotation matrices. Needed for inverse linear-blend skinning / un-posing clients.
MHR scale parameters (isotropic or per-axis).
MHR facial-expression parameters.
Skeleton joint positions in world space [[x, y, z], ...]. One row per MHR joint.
Packed MHR parameter vector (concatenated shape/pose/expression/scale). Shape is forwarded as-is from the upstream model.
Raw pose transforms produced by the MHR decoder (pre-FK), forwarded as-is from the upstream model.