Tripo API Docs

Try FLUX 3 Max, post-trained by fal

tripo3dtripov2.5

Inference

Private

Inference

Private

Playground API

API

1. Calling the API#

Install the client#

The client provides a convenient way to interact with the model API.

npm install --save @fal-ai/client

Migrate to @fal-ai/client

The @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.

Setup your API Key#

Set FAL_KEY as an environment variable in your runtime.

export FAL_KEY="YOUR_API_KEY"

Submit a request#

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);

2. Authentication#

The API uses an API Key for authentication. It is recommended you set the FAL_KEY environment variable in your runtime when possible.

API Key#

In an environment where you cannot set environment variables, you can configure the API key manually on the client.

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

fal.config({
  credentials: "YOUR_FAL_KEY"
});

Protect your API 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.

3. Queue#

Long-running requests

For long-running requests, such as training jobs or models with slower inference times, it is recommended to check the Queue status and rely on Webhooks instead of blocking while waiting for the result.

Submit a request#

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",
});

Fetch request status#

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,
});

Get the result#

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);

4. Files#

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.

Data URI (base64)#

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.

Hosted files (URL)#

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.

Uploading files#

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);

Auto uploads

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.

5. Schema#

Input#

seed integer

This 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 integer

Limits the number of faces on the output model. If this option is not set, the face limit will be adaptively determined.

pbr boolean

A 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 TextureEnum

An 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 integer

This 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 boolean

Automatically scale the model to real-world dimensions, with the unit in meters. The default value is False.

quad boolean

Set 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* required

Text 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 string

Unlike prompt, it provides a reverse direction to assist in generating content contrasting with the original prompt. The maximum length is 255 characters.

image_seed integer

This 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."
}

Output#

task_id string* required

The task id of the 3D model generation.

model_mesh File

Model

base_model File

Base model

pbr_model File

Pbr model

rendered_image File

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"
  }
}

Other types#

File#

url string* required

The URL where the file can be downloaded from.

content_type string

The mime type of the file.

file_name string

The name of the file. It will be auto-generated if not provided.

file_size integer

The size of the file in bytes.

API

1. Calling the API#

Install the client#

The client provides a convenient way to interact with the model API.

npm install --save @fal-ai/client

Migrate to @fal-ai/client

The @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.

Setup your API Key#

Set FAL_KEY as an environment variable in your runtime.

export FAL_KEY="YOUR_API_KEY"

Submit a request#

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);

2. Authentication#

The API uses an API Key for authentication. It is recommended you set the FAL_KEY environment variable in your runtime when possible.

API Key#

In an environment where you cannot set environment variables, you can configure the API key manually on the client.

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

fal.config({
  credentials: "YOUR_FAL_KEY"
});

Protect your API Key

3. Queue#

Long-running requests

Submit a request#

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",
});

Fetch request status#

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,
});

Get the result#

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);

4. Files#

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.

Data URI (base64)#

Hosted files (URL)#

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.

Uploading files#

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);

Auto uploads

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.

5. Schema#

Input#

seed integer

face_limit integer

Limits the number of faces on the output model. If this option is not set, the face limit will be adaptively determined.

pbr boolean

A 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 TextureEnum

An 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 integer

auto_size boolean

Automatically scale the model to real-world dimensions, with the unit in meters. The default value is False.

quad boolean

prompt string* required

negative_prompt string

Unlike prompt, it provides a reverse direction to assist in generating content contrasting with the original prompt. The maximum length is 255 characters.

image_seed integer

This 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."
}

Output#

task_id string* required

The task id of the 3D model generation.

model_mesh File

Model

base_model File

Base model

pbr_model File

Pbr model

rendered_image File

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"
  }
}

Other types#

File#

url string* required

The URL where the file can be downloaded from.

content_type string

The mime type of the file.

file_name string

The name of the file. It will be auto-generated if not provided.

file_size integer

The size of the file in bytes.