# VGGT-1B > Turn images or video into a detailed 3D scene with depth, camera poses, and a colored point cloud. ## Overview - **Endpoint**: `https://fal.run/fal-ai/vggt-1b` - **Model ID**: `fal-ai/vggt-1b` - **Category**: image-to-json - **Kind**: inference ## Pricing - **Price**: $0.000975 per compute seconds For more details, see [fal.ai pricing](https://fal.ai/pricing). ## API Information This model can be used via our HTTP API or more conveniently via our client libraries. See the input and output schema below, as well as the usage examples. ### Input Schema The API accepts the following input parameters: - **`image_urls`** (`list`, _optional_): Input images to reconstruct. Accepts JPEG, PNG, WEBP and the other formats Pillow decodes. Images are padded to a square and resized so the longest side is 518 pixels. - Array of string - Examples: ["https://storage.googleapis.com/falserverless/example_inputs/dog.png"] - **`video_url`** (`string`, _optional_): Optional input video. Frames are sampled every `frame_sampling_rate`-th frame (the first and last frames are always included) and appended after `image_urls`. - **`frame_sampling_rate`** (`integer`, _optional_): Sample every n-th frame of `video_url`. The first and last frames of the video are always included. Ignored when no video is given. Default value: `24` - Default: `24` - Range: `1` to `1000` - **`alpha_blend_onto`** (`AlphaBlendOntoEnum`, _optional_): How to handle images with an alpha channel. 'white'/'black' composite onto that background, 'mean' composites onto the ImageNet mean RGB, and 'keep' discards alpha and keeps the original pixel values. Default value: `"white"` - Default: `"white"` - Options: `"keep"`, `"white"`, `"black"`, `"mean"` - **`export_prediction_data`** (`boolean`, _optional_): Return one JSON file per frame with the raw model outputs (camera pose encoding, depth, depth confidence, mask). Default value: `true` - Default: `true` - **`export_depth_maps`** (`boolean`, _optional_): Return one 16-bit grayscale PNG depth raster per frame. Pixel values map linearly from `depth_range` onto 0-65535. Default value: `true` - Default: `true` - **`export_point_cloud`** (`boolean`, _optional_): Return a GLB scene holding the fused coloured point cloud plus a cone mesh per estimated camera. Default value: `true` - Default: `true` - **`array_encoding`** (`ArrayEncodingEnum`, _optional_): How arrays are encoded inside the prediction JSON files. 'base64' emits {data, shape, dtype} objects; 'list' emits nested JSON lists, which are far larger. Default value: `"base64"` - Default: `"base64"` - Options: `"base64"`, `"list"` - **`exclude_keys`** (`list`, _optional_): Keys to omit from each prediction JSON file. - Array of Enum - **`confidence_percentile`** (`float`, _optional_): Drop this percentage of the lowest-confidence points before building the point cloud. 0 keeps every point. Default value: `50` - Default: `50` - Range: `0` to `100` - **`max_points`** (`integer`, _optional_): Upper bound on the number of points written to the GLB. Points above the default 250,000-point budget are evenly subsampled to limit GLB serialization and upload latency. Default value: `250000` - Default: `250000` - Range: `1000` to `5000000` - **`enable_safety_checker`** (`boolean`, _optional_): Enable safety checking of the input images and video. Default value: `true` - Default: `true` **Required Parameters Example**: ```json {} ``` **Full Example**: ```json { "image_urls": [ "https://storage.googleapis.com/falserverless/example_inputs/dog.png" ], "frame_sampling_rate": 24, "alpha_blend_onto": "white", "export_prediction_data": true, "export_depth_maps": true, "export_point_cloud": true, "array_encoding": "base64", "confidence_percentile": 50, "max_points": 250000, "enable_safety_checker": true } ``` ### Output Schema The API returns the following output format: - **`point_cloud`** (`File`, _optional_): GLB scene with the fused point cloud and camera cones (when `export_point_cloud` is true). - **`depth_maps`** (`list`, _optional_): One 16-bit grayscale PNG depth raster per frame, in frame order (when `export_depth_maps` is true). - Array of Image - **`prediction_data`** (`list`, _optional_): One JSON file of raw predictions per frame, in frame order (when `export_prediction_data` is true). - Array of File - **`num_frames`** (`integer`, _required_): Number of frames reconstructed (images plus sampled video frames). - **`depth_range`** (`list`, _required_): The [min, max] depth used to quantize `depth_maps`. depth = min + (pixel / 65535) * (max - min). - Array of float - **`extrinsics`** (`list>>`, _required_): Per-frame 3x4 camera-from-world extrinsics in OpenCV convention (x-right, y-down, z-forward). - Array of list> - **`intrinsics`** (`list>>`, _required_): Per-frame 3x3 pinhole intrinsics, in pixels of the 518x518 model frame. - Array of list> - **`timings`** (`Timings`, _optional_): Wall-clock seconds per stage. **Example Response**: ```json { "depth_maps": [ { "url": "", "content_type": "image/png", "file_name": "z9RV14K95DvU.png", "file_size": 4404019, "width": 1024, "height": 1024 } ], "prediction_data": [ { "url": "", "content_type": "image/png", "file_name": "z9RV14K95DvU.png", "file_size": 4404019 } ] } ``` ## Usage Examples ### cURL ```bash curl --request POST \ --url https://fal.run/fal-ai/vggt-1b \ --header "Authorization: Key $FAL_KEY" \ --header "Content-Type: application/json" \ --data '{}' ``` ### Python Ensure you have the Python client installed: ```bash pip install fal-client ``` Then use the API client to make requests: ```python import fal_client def on_queue_update(update): if isinstance(update, fal_client.InProgress): for log in update.logs: print(log["message"]) result = fal_client.subscribe( "fal-ai/vggt-1b", arguments={}, with_logs=True, on_queue_update=on_queue_update, ) print(result) ``` ### JavaScript Ensure you have the JavaScript client installed: ```bash npm install --save @fal-ai/client ``` Then use the API client to make requests: ```javascript import { fal } from "@fal-ai/client"; const result = await fal.subscribe("fal-ai/vggt-1b", { input: {}, 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); ``` ## Additional Resources ### Documentation - [Model Playground](https://fal.ai/models/fal-ai/vggt-1b) - [API Documentation](https://fal.ai/models/fal-ai/vggt-1b/api) - [OpenAPI Schema](https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/vggt-1b) ### fal.ai Platform - [Platform Documentation](https://fal.ai/docs/documentation) - [Python Client](https://fal.ai/docs/api-reference/client-libraries/python) - [JavaScript Client](https://fal.ai/docs/api-reference/client-libraries/javascript) ### Other agent-readable surfaces This file covers one model. To find anything else: - [Platform overview](https://fal.ai/llms.txt): Entry points and representative endpoint IDs - [Documentation index](https://fal.ai/docs/llms.txt): Every documentation page - [Full documentation text](https://fal.ai/docs/llms-full.txt): The whole documentation inlined - Any other model: `https://fal.ai/models//llms.txt`