Loading API documentation
/max without the stereo model and the repaint: the fast path.
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("speridlabs/idol/max/turbo", {
input: {
image_url: "https://v3b.fal.media/files/b/0ab21819/3xTHAXZi41yCcq25k0uZY_YGG7j3lg.png"
},
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("speridlabs/idol/max/turbo", {
input: {
image_url: "https://v3b.fal.media/files/b/0ab21819/3xTHAXZi41yCcq25k0uZY_YGG7j3lg.png"
},
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("speridlabs/idol/max/turbo", {
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("speridlabs/idol/max/turbo", {
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.
image_url string* requiredURL of the image of a single object to convert into a game-ready 3D mesh.
enable_pbr booleanAdd roughness and metallic maps to the game-ready mesh with a TRELLIS.2 retexture of the preprocessed image; the base color is not changed. Adds typically 20 seconds to 2 minutes.
rig booleanAlso return rigged_character_glb: the game-ready mesh with a skeleton and skin weights from SkinTokens, for characters and creatures (bipeds, quadrupeds, winged or tailed). game_glb stays without a skeleton. Rigid props such as chests get an unusable skeleton. Adds about 15 seconds (about 60 more on a runner's first such request, which loads the model).
Looping clips to write into rigged_character_glb as glTF animations; each is also returned alone in a file of the result's animations. Requires rig. Each is a hand-made animation of a human or of a four-legged animal, played in place on the limbs found from the skeleton and the skin; a clip the skeleton cannot play (walk, run and jump need two legs, or three or four on an animal) is left out, see rig.animations in the result.
image_type ImageTypeEnumKind of input image. synthetic for renders and generated images (tight crop), real for photographs (looser crop). Default value: "synthetic"
Possible enum values: synthetic, real
num_gaussians integerTarget number of Gaussians in the output splat. Rounded down to a multiple of 32. Default value: 262144
num_inference_steps integerNumber of sampling steps. Fewer are faster but lose some detail. Default value: 50
guidance_scale floatClassifier-free guidance: how strictly the object follows the image. Default value: 3
seed integerRandom seed for reproducibility. If None, a random seed is generated.
enable_safety_checker booleanEnable safety checking of the input image. Default value: true
mesh_resolution MeshResolutionEnumSurface detail. The surface is fused from rendered splat depth on a grid of 0.75 x this many voxels along the object's longest side (1024 -> 768), capped near 80M voxels for bulky objects. Lower values are faster and coarser; above 1024 mostly adds time. Default value: "1024"
Possible enum values: 128, 256, 512, 768, 1024, 1536
{
"image_url": "https://v3b.fal.media/files/b/0ab21819/3xTHAXZi41yCcq25k0uZY_YGG7j3lg.png",
"animations": [],
"image_type": "synthetic",
"num_gaussians": 262144,
"num_inference_steps": 50,
"guidance_scale": 3,
"enable_safety_checker": true,
"mesh_resolution": 1024
}The game-ready mesh with its skeleton, skin weights and all the requested animations in one file (.glb). Only with rig, when the object could be rigged.
One file per requested animation that was written, in the order of the request: the rigged mesh with that clip alone. Empty without rig, when the object could not be rigged or when no animation was requested.
Game-ready mesh (.glb), without a skeleton: 30k triangles, UVs, base color and normal map at 2048 px. On /max the base color is repainted from the image; on /max/turbo it is projected from the splat. With enable_pbr, also a metallic/roughness map.
Full-resolution vertex-colored triangle mesh (.glb), upright in glTF +Y-up coordinates.
The skeleton of rigged_character_glb, added by rig, and the clips written into that file; absent without rig.
The background-removed, cropped image the model saw.
num_gaussians integer* requiredNumber of Gaussians in the intermediate splat.
Triangle mesh geometry and closure information.
seed integer* requiredThe seed used for generation.
Per-stage timings in seconds.
{
"animations": [],
"game_glb": {
"url": "",
"content_type": "image/png",
"file_name": "z9RV14K95DvU.png",
"file_size": 4404019
},
"model_glb": {
"url": "",
"content_type": "image/png",
"file_name": "z9RV14K95DvU.png",
"file_size": 4404019
},
"preprocessed_image": {
"url": "",
"content_type": "image/png",
"file_name": "z9RV14K95DvU.png",
"file_size": 4404019,
"width": 1024,
"height": 1024
},
"mesh_stats": {}
}succeeded boolean* requiredWhether the object was rigged. False when the model could not rig it: the game-ready mesh is then returned without a skeleton.
num_bones integer* requiredNumber of bones in the skeleton; 0 on failure.
Clips written into the game-ready mesh, among those requested.
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.
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.
num_vertices integer* requiredNumber of vertices in the triangle mesh.
num_faces integer* requiredNumber of triangles in the full-resolution mesh.
watertight boolean* requiredAlways true: every edge belongs to exactly two triangles; nonclosed extractions are rejected.
action_id string* requiredName of the clip: walk, run, jump or idle.
The rigged game-ready mesh with this clip alone (.glb).