# Hyper3d

> Rodin by Hyper3D generates realistic and production ready 3D models from text or images.


## Overview

- **Endpoint**: `https://fal.run/fal-ai/hyper3d/rodin/v2`
- **Model ID**: `fal-ai/hyper3d/rodin/v2`
- **Category**: image-to-3d
- **Kind**: inference
**Tags**: image-to-3d, text-to-3d



## Pricing

- **Price**: $0.4 per generations

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:


- **`prompt`** (`string`, _optional_):
  A textual prompt to guide model generation. Optional for Image-to-3D mode - if empty, AI will generate a prompt based on your images. Default value: `""`
  - Default: `""`
  - Examples: "A futuristic robot with sleek metallic design."

- **`input_image_urls`** (`list<string>`, _optional_):
  URL of images to use while generating the 3D model. Required for Image-to-3D mode. Up to 5 images allowed.
  - Array of string
  - Examples: ["https://v3.fal.media/files/panda/l7mQrG8plbB42lBNqVjm0_image.png","https://v3b.fal.media/files/b/kangaroo/scq50Bf1PB2NZOW8szphV_image.png","https://v3.fal.media/files/penguin/X21qtlVMazAtljzRCJD2__image.png"]

- **`use_original_alpha`** (`boolean`, _optional_):
  When enabled, preserves the transparency channel from input images during 3D generation.
  - Default: `false`

- **`seed`** (`integer`, _optional_):
  Seed value for randomization, ranging from 0 to 65535. Optional.
  - Range: `0` to `65535`

- **`geometry_file_format`** (`GeometryFileFormatEnum`, _optional_):
  Format of the geometry file. Possible values: glb, usdz, fbx, obj, stl. Default is glb. Default value: `"glb"`
  - Default: `"glb"`
  - Options: `"glb"`, `"usdz"`, `"fbx"`, `"obj"`, `"stl"`

- **`material`** (`MaterialEnum`, _optional_):
  Material type. PBR: Physically-based materials with realistic lighting. Shaded: Simple materials with baked lighting. All: Both types included. Default value: `"All"`
  - Default: `"All"`
  - Options: `"PBR"`, `"Shaded"`, `"All"`

- **`quality_mesh_option`** (`QualityMeshOptionEnum`, _optional_):
  Combined quality and mesh type selection. Quad = smooth surfaces, Triangle = detailed geometry. These corresponds to `mesh_mode` (if the option contains 'Triangle', mesh_mode is 'Raw', otherwise 'Quad') and `quality_override` (the numeric part of the option) parameters in Hyper3D API. Default value: `"500K Triangle"`
  - Default: `"500K Triangle"`
  - Options: `"4K Quad"`, `"8K Quad"`, `"18K Quad"`, `"50K Quad"`, `"2K Triangle"`, `"20K Triangle"`, `"150K Triangle"`, `"500K Triangle"`

- **`TAPose`** (`boolean`, _optional_):
  Generate characters in T-pose or A-pose format, making them easier to rig and animate in 3D software.
  - Default: `false`

- **`bbox_condition`** (`list<integer>`, _optional_):
  An array that specifies the bounding box dimensions [width, height, length].
  - Array of integer

- **`addons`** (`string`, _optional_):
  The HighPack option will provide 4K resolution textures instead of the default 1K, as well as models with high-poly. It will cost **triple the billable units**.

- **`preview_render`** (`boolean`, _optional_):
  Generate a preview render image of the 3D model along with the model files.
  - Default: `false`



**Required Parameters Example**:

```json
{}
```

**Full Example**:

```json
{
  "prompt": "A futuristic robot with sleek metallic design.",
  "input_image_urls": [
    "https://v3.fal.media/files/panda/l7mQrG8plbB42lBNqVjm0_image.png",
    "https://v3b.fal.media/files/b/kangaroo/scq50Bf1PB2NZOW8szphV_image.png",
    "https://v3.fal.media/files/penguin/X21qtlVMazAtljzRCJD2__image.png"
  ],
  "geometry_file_format": "glb",
  "material": "All",
  "quality_mesh_option": "500K Triangle"
}
```


### Output Schema

The API returns the following output format:

- **`model_mesh`** (`File`, _required_):
  Generated 3D object file.
  - Examples: {"url":"https://storage.googleapis.com/falserverless/model_tests/video_models/base_basic_shaded.glb"}

- **`model_meshes`** (`list<File>`, _optional_):
  Additional generated 3D object files returned by Hyper3D besides model_mesh.
  - Array of File

- **`seed`** (`integer`, _required_):
  Seed value used for generation.

- **`textures`** (`list<Image>`, _required_):
  Generated textures for the 3D object.
  - Array of Image



**Example Response**:

```json
{
  "model_mesh": {
    "url": "https://storage.googleapis.com/falserverless/model_tests/video_models/base_basic_shaded.glb"
  },
  "model_meshes": [
    {
      "url": "",
      "content_type": "image/png",
      "file_name": "z9RV14K95DvU.png",
      "file_size": 4404019
    }
  ],
  "textures": [
    {
      "url": "",
      "content_type": "image/png",
      "file_name": "z9RV14K95DvU.png",
      "file_size": 4404019,
      "width": 1024,
      "height": 1024
    }
  ]
}
```


## Usage Examples

### cURL

```bash
curl --request POST \
  --url https://fal.run/fal-ai/hyper3d/rodin/v2 \
  --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/hyper3d/rodin/v2",
    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/hyper3d/rodin/v2", {
  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/hyper3d/rodin/v2)
- [API Documentation](https://fal.ai/models/fal-ai/hyper3d/rodin/v2/api)
- [OpenAPI Schema](https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/hyper3d/rodin/v2)

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