Loading API documentation
Text To 3D
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("tripo3d/tripo/v2.5/text-to-3d", {
input: {
prompt: "A stylized cartoon man standing with arms crossed, wearing a light grey sweatshirt, blue jeans, and dark red sneakers with white soles. He has short dark brown hair, a full beard, and large red round glasses. The figure stands confidently, with a friendly but serious expression. Light blue background. Upright posture."
},
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("tripo3d/tripo/v2.5/text-to-3d", {
input: {
prompt: "A stylized cartoon man standing with arms crossed, wearing a light grey sweatshirt, blue jeans, and dark red sneakers with white soles. He has short dark brown hair, a full beard, and large red round glasses. The figure stands confidently, with a friendly but serious expression. Light blue background. Upright posture."
},
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("tripo3d/tripo/v2.5/text-to-3d", {
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("tripo3d/tripo/v2.5/text-to-3d", {
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.
seed integerThis is the random seed for model generation. The seed controls the geometry generation process, ensuring identical models when the same seed is used. This parameter is an integer and is randomly chosen if not set.
face_limit integerLimits the number of faces on the output model. If this option is not set, the face limit will be adaptively determined.
pbr booleanA boolean option to enable pbr. The default value is True, set False to get a model without pbr. If this option is set to True, texture will be ignored and used as True.
texture TextureEnumAn option to enable texturing. Default is 'standard', set 'no' to get a model without any textures, and set 'HD' to get a model with hd quality textures. Default value: "standard"
Possible enum values: no, standard, HD
texture_seed integerThis is the random seed for texture generation. Using the same seed will produce identical textures. This parameter is an integer and is randomly chosen if not set. If you want a model with different textures, please use same seed and different texture_seed.
auto_size booleanAutomatically scale the model to real-world dimensions, with the unit in meters. The default value is False.
quad booleanSet True to enable quad mesh output (extra $0.05 per generation). If quad=True and face_limit is not set, the default face_limit will be 10000. Note: Enabling this option will force the output to be an FBX model.
prompt string* requiredText input that directs the model generation. The maximum prompt length is 1024 characters, equivalent to approximately 100 words. The API supports multiple languages. However, emojis and certain special Unicode characters are not supported.
negative_prompt stringUnlike prompt, it provides a reverse direction to assist in generating content contrasting with the original prompt. The maximum length is 255 characters.
image_seed integerThis is the random seed used for the process based on the prompt. This parameter is an integer and is randomly chosen if not set.
{
"texture": "standard",
"prompt": "A stylized cartoon man standing with arms crossed, wearing a light grey sweatshirt, blue jeans, and dark red sneakers with white soles. He has short dark brown hair, a full beard, and large red round glasses. The figure stands confidently, with a friendly but serious expression. Light blue background. Upright posture.",
"negative_prompt": "No distortion, no missing limbs, no broken fingers, no blurry textures, no floating parts, no wrong colors, no unrealistic body proportions, no background objects."
}task_id string* requiredThe task id of the 3D model generation.
Model
Base model
Pbr model
A preview image of the model
{
"task_id": "",
"model_mesh": {
"url": "https://v3.fal.media/files/zebra/NA4WkhbpI-XdOIFc4cDIk_tripo_model_812c3a8a-6eb3-4c09-9f40-0563d27ae7ea.glb",
"file_size": 6744644,
"content_type": "application/octet-stream"
},
"rendered_image": {
"url": "https://v3.fal.media/files/panda/zDTAHqp8ifMOT3upZ1xJv_legacy.webp",
"file_size": 13718,
"content_type": "image/webp"
}
}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.