# hyper3d/rodin-v2.5/text-to-3d

> Hyper3D Rodin v2.5 Text to 3D is a fast AI 3D asset generation model that creates production-ready 3D assets from text prompts with clean meshes, UVs, and textures. Ready-to-use REST inference API for game assets, e-commerce 3D models, product visualization, AR/VR content, digital twins, creative design, and professional text-to-3D workflows with simple integration, no coldstarts, and affordable pricing.

## Overview

- **Endpoint**: `https://api.wavespeed.ai/api/v3/hyper3d/rodin-v2.5/text-to-3d`
- **Polling/result URL**: `https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result`
- **Model ID**: `hyper3d/rodin-v2.5/text-to-3d`
- **Category**: text-to-3d

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
The API is asynchronous: submit a prediction, then poll its result URL until it completes.

### Input Schema

The API accepts the following input parameters:

- **`prompt`** (`string`, _required_):
  A text prompt describing the 3D asset to generate.

- **`tier`** (`string`, _optional_):
  Generation tier. Extreme-High bills at double the base rate.
  - Default: `"Gen-2.5-Medium"`
  - Options: "Gen-2.5-Extreme-Low", "Gen-2.5-Low", "Gen-2.5-Medium", "Gen-2.5-High", "Gen-2.5-Extreme-High"

- **`geometry_file_format`** (`string`, _optional_):
  Output geometry file format.
  - Default: `"glb"`
  - Options: "glb", "usdz", "fbx", "obj", "stl"

- **`material`** (`string`, _optional_):
  Material output type.
  - Default: `"All"`
  - Options: "PBR", "Shaded", "All", "None"

- **`quality_and_mesh`** (`string`, _optional_):
  Combined quality and mesh type selection.
  - Default: `"18K Quad"`
  - Options: "4K Quad", "8K Quad", "18K Quad", "50K Quad", "2K Triangle", "20K Triangle", "150K Triangle", "500K Triangle"

- **`texture_mode`** (`string`, _optional_):
  Texture generation quality. Leave empty to use the model default.
  - Options: "legacy", "extreme-low", "low", "medium", "high"

- **`geometry_instruct_mode`** (`string`, _optional_):
  Faithful follows the prompt closely; creative allows more variation.
  - Default: `"faithful"`
  - Options: "faithful", "creative"

- **`hd_texture`** (`boolean`, _optional_):
  Enable enhanced texture post-processing.
  - Default: `false`

- **`texture_delight`** (`boolean`, _optional_):
  Remove baked lighting and highlights from generated textures.
  - Default: `false`

- **`is_micro`** (`boolean`, _optional_):
  Generate finer micro-scale geometric detail. Only effective with Extreme-High tier.
  - Default: `false`

- **`ta_pose`** (`boolean`, _optional_):
  Generate characters in T-pose or A-pose format.
  - Default: `false`

- **`addons`** (`string`, _optional_):
  Optional HighPack add-on for 4K textures and higher-poly geometry.
  - Options: "HighPack"



**Required Parameters Example**:

```json
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed"
}
```

**Full Example**:

```json
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "tier": "Gen-2.5-Medium",
  "geometry_file_format": "glb",
  "material": "All",
  "quality_and_mesh": "18K Quad",
  "texture_mode": "legacy",
  "geometry_instruct_mode": "faithful",
  "hd_texture": false,
  "texture_delight": false,
  "is_micro": false,
  "ta_pose": false,
  "addons": "HighPack"
}
```

### Result Data Schema

The `data` object returned by the API has the following fields:

- **`created_at`** (`string (date-time)`, _optional_):
  ISO timestamp of when the request was created (e.g., "2023-04-01T12:34:56.789Z").

- **`id`** (`string`, _optional_):
  Unique identifier for the prediction, the ID of the prediction to get.

- **`model`** (`string`, _optional_):
  Model ID used for the prediction.

- **`outputs`** (`array of string | object`, _optional_):
  Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.

- **`status`** (`string`, _optional_):
  Status of the task: created, processing, completed, or failed.

- **`urls`** (`object`, _optional_):
  Object containing related API endpoints.



**Example `data` Object**:

```json
{
  "created_at": "example",
  "id": "example",
  "model": "example",
  "outputs": [],
  "status": "example",
  "urls": {}
}
```

## Usage Examples

The examples use `jq` to read JSON. Set your API key first:

```bash
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
```

### 1. Submit a prediction

```bash
REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed"
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.wavespeed.ai/api/v3/hyper3d/rodin-v2.5/text-to-3d \
  --header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "${REQUEST_BODY}")

printf '%s\n' "${SUBMIT_RESPONSE}" | jq .
```

The response contains the prediction ID in `data.id`.

### 2. Poll until complete and read `outputs`

```bash
PREDICTION_ID=$(printf '%s' "${SUBMIT_RESPONSE}" | jq -r '.data.id')
if [ -z "${PREDICTION_ID}" ] || [ "${PREDICTION_ID}" = "null" ]; then
  printf 'Submission response did not contain data.id\n' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    --request GET \
    --url "${RESULT_URL}" \
    --header "Authorization: Bearer ${WAVESPEED_API_KEY}")

  RESULT=$(printf '%s' "${RESPONSE}" | jq -e '.data')
  STATUS=$(printf '%s' "${RESULT}" | jq -er '.status')
  case "${STATUS}" in
    completed)
      # Generated files are returned in the outputs array.
      printf '%s\n' "${RESULT}" | jq '.outputs'
      break
      ;;
    failed|cancelled|timeout|deleted)
      printf '%s\n' "${RESULT}" | jq '{status, error, code}'
      exit 1
      ;;
    *)
      sleep 2
      ;;
  esac
done
```

## Additional Resources

### Documentation

- [Model Playground](https://wavespeed.ai/models/hyper3d/rodin-v2.5/text-to-3d)
- [API Documentation](https://wavespeed.ai/docs/docs-api/hyper3d/hyper3d-rodin-v2.5-text-to-3d)