# Pixal3d

> Pixal3D turns a single image into a high-fidelity 3D model with detailed geometry and realistic textures.


## Overview

- **Endpoint**: `https://fal.run/fal-ai/pixal3d`
- **Model ID**: `fal-ai/pixal3d`
- **Category**: image-to-3d
- **Kind**: inference
**Tags**: stylized, transform



## Pricing

Your request will cost **$0.3** for **1024p** resolution, **$0.42** for **2048p** and **4096p** resolutions

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_url`** (`string`, _required_):
  URL of the input image to convert to 3D
  - Examples: "https://storage.googleapis.com/falserverless/example_inputs/dog.png"

- **`seed`** (`integer`, _optional_):
  Random seed for reproducibility

- **`resolution`** (`ResolutionEnum`, _optional_):
  Output resolution; higher is slower but more detailed Default value: `"1024"`
  - Default: `1024`
  - Options: `1024`, `1536`

- **`ss_guidance_strength`** (`float`, _optional_):
  How closely the initial 3D structure follows the input image. Higher values produce more faithful but potentially noisier results. Default value: `7.5`
  - Default: `7.5`
  - Range: `0` to `10`

- **`ss_guidance_rescale`** (`float`, _optional_):
  Dampens artifacts from high guidance in stage 1. Lower values allow stronger guidance effects, higher values stabilize the output. Default value: `0.7`
  - Default: `0.7`
  - Range: `0` to `1`

- **`ss_sampling_steps`** (`integer`, _optional_):
  Number of denoising steps for the initial structure. More steps = slower but potentially higher quality. Default value: `12`
  - Default: `12`
  - Range: `1` to `50`

- **`ss_rescale_t`** (`float`, _optional_):
  Controls noise schedule sharpness for structure generation. Higher values produce sharper transitions. Default value: `5`
  - Default: `5`
  - Range: `1` to `6`

- **`shape_slat_guidance_strength`** (`float`, _optional_):
  How closely the detailed geometry follows the input image. Higher values add more detail but may introduce noise. Default value: `7.5`
  - Default: `7.5`
  - Range: `0` to `10`

- **`shape_slat_guidance_rescale`** (`float`, _optional_):
  Dampens artifacts from high guidance in the shape stage. Increase if you see noisy geometry. Default value: `0.5`
  - Default: `0.5`
  - Range: `0` to `1`

- **`shape_slat_sampling_steps`** (`integer`, _optional_):
  Number of denoising steps for shape refinement. More steps = slower but potentially smoother geometry. Default value: `12`
  - Default: `12`
  - Range: `1` to `50`

- **`shape_slat_rescale_t`** (`float`, _optional_):
  Controls noise schedule sharpness for shape refinement. Higher values produce sharper geometric details. Default value: `3`
  - Default: `3`
  - Range: `1` to `6`

- **`tex_slat_guidance_strength`** (`float`, _optional_):
  How closely the texture follows the input image colors. Higher values produce more vivid but potentially oversaturated textures. Default value: `1`
  - Default: `1`
  - Range: `0` to `10`

- **`tex_slat_guidance_rescale`** (`float`, _optional_):
  Dampens artifacts from high guidance in the texture stage. Increase if textures look noisy or have color banding.
  - Default: `0`
  - Range: `0` to `1`

- **`tex_slat_sampling_steps`** (`integer`, _optional_):
  Number of denoising steps for texture generation. More steps = slower but potentially cleaner textures. Default value: `12`
  - Default: `12`
  - Range: `1` to `50`

- **`tex_slat_rescale_t`** (`float`, _optional_):
  Controls noise schedule sharpness for texture generation. Higher values produce sharper texture details. Default value: `3`
  - Default: `3`
  - Range: `1` to `6`

- **`mesh_scale`** (`float`, _optional_):
  Scale factor applied to the inferred mesh. Affects the camera distance estimation used by the model. Default value: `1`
  - Default: `1`
  - Range: `0.1` to `4`

- **`max_num_tokens`** (`integer`, _optional_):
  Maximum number of HR tokens used by the cascaded shape sampler. Higher values allow finer geometry; lower values reduce memory and time. Default value: `49152`
  - Default: `49152`
  - Range: `4096` to `131072`

- **`decimation_target`** (`integer`, _optional_):
  Target number of vertices in the final mesh. Lower values produce smaller files but less detail. Default value: `200000`
  - Default: `200000`
  - Range: `5000` to `2000000`

- **`texture_size`** (`TextureSizeEnum`, _optional_):
  Resolution of the texture image baked onto the mesh. Higher values capture finer surface details but produce larger files. Default value: `"2048"`
  - Default: `2048`
  - Options: `1024`, `2048`, `4096`

- **`remesh`** (`boolean`, _optional_):
  Rebuild the mesh topology for cleaner triangles. Slower but usually produces better results for downstream use. Default value: `true`
  - Default: `true`



**Required Parameters Example**:

```json
{
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/dog.png"
}
```

**Full Example**:

```json
{
  "image_url": "https://storage.googleapis.com/falserverless/example_inputs/dog.png",
  "resolution": 1024,
  "ss_guidance_strength": 7.5,
  "ss_guidance_rescale": 0.7,
  "ss_sampling_steps": 12,
  "ss_rescale_t": 5,
  "shape_slat_guidance_strength": 7.5,
  "shape_slat_guidance_rescale": 0.5,
  "shape_slat_sampling_steps": 12,
  "shape_slat_rescale_t": 3,
  "tex_slat_guidance_strength": 1,
  "tex_slat_sampling_steps": 12,
  "tex_slat_rescale_t": 3,
  "mesh_scale": 1,
  "max_num_tokens": 49152,
  "decimation_target": 200000,
  "texture_size": 2048,
  "remesh": true
}
```


### Output Schema

The API returns the following output format:

- **`model_glb`** (`File`, _required_):
  Generated 3D GLB file
  - Examples: {"url":"https://v3b.fal.media/files/b/0a86b61d/DNmTkiWHUQ8k-rG6aussB_trellis2_68d6300f70f34d23b69a912b5fe60487.glb"}

- **`seed`** (`integer`, _required_):
  The actual seed used



**Example Response**:

```json
{
  "model_glb": {
    "url": "https://v3b.fal.media/files/b/0a86b61d/DNmTkiWHUQ8k-rG6aussB_trellis2_68d6300f70f34d23b69a912b5fe60487.glb"
  }
}
```


## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://fal.run/fal-ai/pixal3d \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data '{
     "image_url": "https://storage.googleapis.com/falserverless/example_inputs/dog.png"
   }'
```

### 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/pixal3d",
    arguments={
        "image_url": "https://storage.googleapis.com/falserverless/example_inputs/dog.png"
    },
    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/pixal3d", {
  input: {
    image_url: "https://storage.googleapis.com/falserverless/example_inputs/dog.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);
```


## Additional Resources

### Documentation

- [Model Playground](https://fal.ai/models/fal-ai/pixal3d)
- [API Documentation](https://fal.ai/models/fal-ai/pixal3d/api)
- [OpenAPI Schema](https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/pixal3d)

### fal.ai Platform

- [Platform Documentation](https://docs.fal.ai)
- [Python Client](https://docs.fal.ai/clients/python)
- [JavaScript Client](https://docs.fal.ai/clients/javascript)