Loading API documentation
Turn a photo into a 3D-printable relief (STL, GLB) and a 2K 16-bit depth map.
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("meshy/relief", {
input: {
image_url: "https://v3b.fal.media/files/b/zebra/3osHJDI8IZ2wl6sGtEUeB_image.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("meshy/relief", {
input: {
image_url: "https://v3b.fal.media/files/b/zebra/3osHJDI8IZ2wl6sGtEUeB_image.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("meshy/relief", {
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("meshy/relief", {
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* requiredPhoto to turn into a relief. Works best with one clear subject on a plain background. JPG, PNG or WebP up to 20 MB.
variant VariantEnumRelief depth. 'low' gives slight depth and finer detail (patterns, badges, seals); 'high' gives bold, sculptural depth (pets, portraits, characters). Default value: "low"
Possible enum values: low, high
should_generate_model booleanGenerate the STL and GLB relief models. Set to false to return only the 16-bit depth map. Default value: true
size_mm floatLength of the photo's long side in millimeters, measured flat before any bend. Default value: 60
carving_mode CarvingModeEnum'emboss' makes the nearer parts stand out; 'engrave' inverts the depth so they are cut in. Default value: "emboss"
Possible enum values: emboss, engrave
carving_depth_mm floatCarving depth in millimeters. Defaults to 3 for 'low' and 6 for 'high'.
remove_base booleanCut away the background and build no base plate. A high removal_threshold, or a carving depth of 0, can produce an empty model.
removal_threshold floatOnly used with remove_base. Depth below which the background is cut, on the depth map's 0-1 scale. Defaults to 0.01.
base_thickness_mm floatBase plate thickness in millimeters. Defaults to 1. Not allowed with remove_base.
bend_mode BendModeEnumBend the relief into a convex or concave curve. Default value: "off"
Possible enum values: off, convex, concave
bend_axis BendAxisEnumBend axis: 'xz' curls the left and right edges, 'yz' the top and bottom. Default value: "xz"
Possible enum values: xz, yz
bend_angle floatBend angle in degrees. Under 1 stays flat. Default value: 60
mesh_resolution integerMesh points along the long side. At 2048, files reach about 150 MB (GLB) and 300 MB (STL), and a bend can push the STL to about 800 MB. Default value: 1024
enable_safety_checker booleanIf set to true, input data will be checked for safety before processing. Default value: true
{
"image_url": "https://v3b.fal.media/files/b/zebra/3osHJDI8IZ2wl6sGtEUeB_image.png",
"variant": "low",
"should_generate_model": true,
"size_mm": 60,
"carving_mode": "emboss",
"bend_mode": "off",
"bend_axis": "xz",
"bend_angle": 60,
"mesh_resolution": 1024,
"enable_safety_checker": true
}16-bit grayscale depth map (PNG, 2K).
Relief model in GLB format. Absent when should_generate_model is false.
Relief model files (GLB and STL). Empty when should_generate_model is false.
Preview image of the relief.
{
"depth_map": {
"url": "",
"content_type": "image/png",
"file_name": "z9RV14K95DvU.png",
"file_size": 4404019
}
}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.