# Hyper3D - Rodin V2.5 - Image to 3D API

> Chuyển ảnh thành 3D với Rodin V2.5 bằng tối đa 5 ảnh tham chiếu và lựa chọn các mức chất lượng

Xây dựng mô hình 3D từ một đến năm hình ảnh trong `image_urls`, với `prompt` tùy chọn dài tối đa 1024 ký tự. Sáu cấp độ chạy từ Gen-2.5-Minimum đến Gen-2.5-Extreme-High, mặc định là High. Các tùy chọn gồm định dạng hình học (glb, usdz, fbx, obj, stl), `material`, kích thước lưới tứ giác hoặc tam giác, `TAPose` cho nhân vật thân thiện với hệ thống gắn khung xương và `hd_texture`.

- Model id: `hyper3d/rodin/v2.5`
- Made by: Hyper3D
- Category: Image to 3D
- Output: 3d
- Price: from $0.40 / request (cheapest run $0.40 (400 API credits))
- Run: `POST https://api.doitong.com/v1/run/hyper3d/rodin/v2.5`
- Quote: `POST https://api.doitong.com/v1/quote/hyper3d/rodin/v2.5`
- Docs page: https://doitong.com/vi/developers/models/hyper3d/rodin/v2.5

## Pricing

Price: **from $0.40 / request** (the lowest tier; the quote prices your exact input). Billed once per request.

Price rules (the first rule that matches the input wins; a parameter you leave out counts as its default):

- When `addons.high_pack` = true: $1.20 (1200 API credits) / request

The full example input below costs $0.40 = 400 API credits (1 request × 400 API credits).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.com/v1/quote/hyper3d/rodin/v2.5` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `prompt` |  | string | no | `` | ≤ 1024 characters | Hướng dẫn tạo sinh bằng văn bản hoặc để mô hình tự động suy ra lời nhắc từ các hình ảnh bằng cách để trống trong chế độ Image-to-3D. |
| `image_urls` | `images` | array of image URL | no |  | 1 – 5 items | URL hình ảnh nguồn, giới hạn 5 hình ảnh và bắt buộc trong chế độ Image-to-3D để tạo mô hình. |
| `tier` |  | enum (string) | no | `Gen-2.5-High` | `Gen-2.5-Minimum`, `Gen-2.5-Extreme-Low`, `Gen-2.5-Low`, `Gen-2.5-Medium`, `Gen-2.5-High`, `Gen-2.5-Extreme-High` | Cấp độ chi tiết lưới; tăng cấp độ sẽ thêm chi tiết, nhưng Gen-2.5-Minimum tự động kích hoạt chế độ minimum và buộc dùng 50K Triangle bất kể quality_mesh_option. Xem thêm trong [tài liệu](https://developer.hyper3d.ai/api-specification/rodin-gen2.5#use-gen-2.5-generation-with-following-gen-2.5-tiers). |
| `use_original_alpha` |  | boolean | no | `false` |  | Kiểm soát việc giữ lại các kênh trong suốt của hình ảnh đầu vào khi tạo nội dung 3D. |
| `seed` |  | integer \| null | no |  | 0 – 65,535 | Seed ngẫu nhiên tùy chọn trong khoảng từ 0–65535. |
| `geometry_file_format` |  | enum (string) | no | `glb` | `glb`, `usdz`, `fbx`, `obj`, `stl` | Định dạng tệp hình học, chọn từ glb, usdz, fbx, obj, stl; mặc định là glb. |
| `material` |  | enum (string) | no | `All` | `PBR`, `Shaded`, `All`, `None` | Lựa chọn đầu ra vật liệu: chọn None cho hình học không có kết cấu hoặc All để nhận cả hai biến thể vật liệu. Để có ánh sáng chân thực với vật liệu dựa trên vật lý, chọn PBR; để có ánh sáng đã nung mà không có bản đồ PBR, chọn Shaded. |
| `quality_mesh_option` |  | enum (string) | no | `Auto` | `Auto`, `4K Quad`, `8K Quad`, `18K Quad`, `50K Quad`, `100K Quad`, `200K Quad`, `2K Triangle`, `20K Triangle`, `50K Triangle`, `150K Triangle`, `500K Triangle`, `1M Triangle`, `2M Triangle` | Chất lượng và cấu trúc liên kết lưới, với số mặt khả dụng do cấp độ quyết định: Extreme-Low, Low và Medium cho phép tối đa 1M Triangle; High và Extreme-High hỗ trợ từ 20K Triangle đến 2M Triangle. Auto áp dụng các thiết lập đề xuất: 1. Gen-2.5-Minimum → 50K Triangle; 2. Gen-2.5-Extreme-Low → 50K Triangle; 3. Gen-2.5-Low → 50K Triangle; 4. Gen-2.5-Medium → 500K Triangle; 5. Gen-2.5-High → 500K Triangle; Gen-2.5-Extreme-High → 1M Triangle. Khi chọn thủ công, Quad ưu tiên bề mặt mượt còn Triangle ưu tiên hình học chi tiết; Hyper3D API nhận cấu trúc liên kết qua `mesh_mode` (Quad/Raw) và số mặt qua `quality_override`. |
| `texture_mode` |  | enum (string) \| null | no |  | `legacy`, `extreme-low`, `low`, `medium`, `high` | Chọn rõ chất lượng kết cấu hoặc để API tự chọn, sử dụng giá trị mặc định phù hợp với cấp độ. |
| `enable_creative_mode` |  | boolean | no | `false` |  | Chế độ tạo sinh sáng tạo, tương đương với `geometry_instruct_mode` đặt thành `creative` trong Hyper3D API. Khi bật, chế độ này giúp quá trình tạo sinh ổn định hơn mà không làm giảm tính nhất quán của đầu ra. |
| `hd_texture` |  | boolean | no | `false` |  | Kiểm soát hậu xử lý kết cấu nâng cao để cải thiện độ trung thực hình ảnh. |
| `texture_delight` |  | boolean | no | `false` |  | Loại bỏ ánh sáng và vùng sáng được tích hợp khỏi các kết cấu đã tạo. |
| `is_micro` |  | boolean | no | `false` |  | Thêm chi tiết hình học tinh hơn ở cấp vi mô; chỉ có hiệu lực khi `tier="Gen-2.5-Extreme-High"`. |
| `TAPose` |  | boolean | no | `false` |  | Thiết lập tư thế nhân vật để dễ tạo khung xương và hoạt ảnh trong phần mềm 3D: khi bật, nhân vật được tạo ở tư thế T hoặc A. |
| `bbox_condition` |  | object {width, height, length} \| null | no |  |  | Giới hạn kích thước tối đa của mô hình được tạo bằng ControlNet. |
| `bbox_condition.width` |  | integer | no | `0` | 1 – 2,048 | Ràng buộc chiều rộng của hộp giới hạn trên trục x. |
| `bbox_condition.height` |  | integer | no | `0` | 1 – 2,048 | Ràng buộc chiều cao của hộp giới hạn trên trục y. |
| `bbox_condition.length` |  | integer | no | `0` | 1 – 2,048 | Ràng buộc chiều dài của hộp giới hạn trên trục z. |
| `addons` |  | object {high_pack} \| null | no |  |  | Lựa chọn tiện ích bổ sung tùy chọn, được cung cấp dưới dạng danh sách hoặc một giá trị đơn nếu chỉ có một tiện ích. |
| `addons.high_pack` |  | boolean | no | `false` |  | Cải tiến HighPack: đầu ra Quad có số mặt xấp xỉ gấp 16 lần số mặt được yêu cầu qua tham số chất lượng, và kết cấu sử dụng độ phân giải 4K thay vì mặc định 2K. |
| `preview_render` |  | boolean | no | `false` |  | Nút bật/tắt kết xuất xem trước, thêm hình ảnh hiển thị mô hình 3D đã tạo vào các tệp mô hình được trả về. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Có thể nới lỏng việc kiểm duyệt bằng cách đặt thành false, nếu người gọi được cấp quyền. |

File parameters (`images`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{}
```

A fuller example:

```json
{
  "prompt": ""
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.com/v1/run/hyper3d/rodin/v2.5?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": ""
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.com/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.com/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/hyper3d/rodin/v2.5?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": ""
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.com/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "prompt": "",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/hyper3d/rodin/v2.5", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.com/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "hyper3d/rodin/v2.5",
      "input": {
        "prompt": ""
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "hyper3d/rodin/v2.5",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 400,
    "usd": "0.40",
    "charged": 400,
    "refunded": 0
  },
  "input": {
    "prompt": ""
  },
  "output": {
    "model_mesh": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "model_meshes": [
      {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200
      }
    ],
    "seed": 42,
    "textures": [
      {
        "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
        "content_type": "image/jpeg",
        "file_name": "0-output.jpeg",
        "file_size": 1843200,
        "width": 1024,
        "height": 768
      }
    ]
  },
  "outputs": [
    {
      "type": "file",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_size": 1843200,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `model_mesh` | object {url, content_type, file_name, file_size} | Tệp chứa đối tượng 3D đã tạo. |
| `model_meshes` | array of object {url, content_type, file_name, file_size} | Các tệp đối tượng 3D bổ sung do Hyper3D tạo và trả về cùng với model_mesh. |
| `seed` | integer | Seed được áp dụng trong quá trình tạo sinh. |
| `textures` | array of object {url, content_type, file_name, file_size, width, height} | Các kết cấu được tạo cho đối tượng 3D. |

## Related models

- [Hyper3D - Rodin V2.5 - Image to 3D - Fast](https://doitong.com/developers/models/hyper3d/rodin/v2.5/fast.md) (`hyper3d/rodin/v2.5/fast`): $0.10 / request
- [Hyper3D - Rodin V2.5 - Text to 3D](https://doitong.com/developers/models/hyper3d/rodin/v2.5/text-to-3d.md) (`hyper3d/rodin/v2.5/text-to-3d`): from $0.40 / request
- [Hyper3D - Rodin V2.5 - Text to 3D - Fast](https://doitong.com/developers/models/hyper3d/rodin/v2.5/text-to-3d/fast.md) (`hyper3d/rodin/v2.5/text-to-3d/fast`): $0.10 / request
- [Hyper3d](https://doitong.com/developers/models/hyper3d/rodin/v2.md) (`hyper3d/rodin/v2`): $0.40 / request
- [Hyper3D Rodin](https://doitong.com/developers/models/hyper3d/rodin.md) (`hyper3d/rodin`): $0.40 / request
- [Hi3D Image to 3D](https://doitong.com/developers/models/hitem3d/hi3d/image-to-3d.md) (`hitem3d/hi3d/image-to-3d`): $0.50 / run
- [Hi3D Image to 3D · v3.0](https://doitong.com/developers/models/hitem3d/hi3d/v3.0/image-to-3d.md) (`hitem3d/hi3d/v3.0/image-to-3d`): from $1.80 / run
- [Hi3D Multiview to 3D · Multi View to 3D](https://doitong.com/developers/models/hitem3d/hi3d/multi-view-to-3d.md) (`hitem3d/hi3d/multi-view-to-3d`): $0.50 / run

## Links

- HTML page: https://doitong.com/developers/models/hyper3d/rodin/v2.5
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=hyper3d/rodin/v2.5
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.com/v1/models/hyper3d/rodin/v2.5