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

> Rodin V2.5 chuyển ảnh thành 3D nhanh, giới hạn ở ba mức thấp nhất để tạo mẫu nhanh

Tạo mô hình 3D từ một đến năm ảnh trong `image_urls`, với `prompt` tùy chọn. `tier` chỉ giới hạn ở Minimum, Extreme-Low (mặc định) và Low, còn tùy chọn lưới tối đa 20K mặt. Material mặc định là Shaded. Định dạng đầu ra là glb, usdz, fbx, obj hoặc stl.

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

## Pricing

Price: **$0.10 / request**. Billed once per request.

The full example input below costs $0.10 = 100 API credits (1 request × 100 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/fast` 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 |
|---|---|---|---|---|---|---|
| `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-Extreme-Low` | `Gen-2.5-Minimum`, `Gen-2.5-Extreme-Low`, `Gen-2.5-Low` | Cấp độ tạo sinh; Gen-2.5-Minimum buộc dùng chế độ minimum và lưới 50K Triangle bất kể `quality_mesh_option`. Chi tiết cấp độ có trong [tài liệu Hyper3D](https://developer.hyper3d.ai/api-specification/rodin-gen2.5#use-gen-2.5-generation-with-following-gen-2.5-tiers). |
| `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. |
| `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 | `Shaded` | `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`, `1K Quad`, `4K Quad`, `8K Quad`, `18K Quad`, `20K Quad`, `2K Triangle`, `4K Triangle`, `8K Triangle`, `10K Triangle`, `20K Triangle` | Chọn chất lượng cùng cấu trúc liên kết lưới: Quad ưu tiên bề mặt mượt, còn Triangle ưu tiên chi tiết hình học. Điểm cuối nhanh chủ yếu dành cho kiểm thử và tạo nguyên mẫu, với giới hạn 20K; dùng điểm cuối tiêu chuẩn để có lưới chất lượng cao hơn, trong đó Minimum, Extreme-Low và Low hỗ trợ tối đa 1M Triangle, với số mặt khả dụng tùy cấp độ. Trong Hyper3D API, `quality_override` chỉ định số mặt, còn `mesh_mode` chỉ định Quad/Raw. Auto chọn các thiết lập đề xuất: 1. Gen-2.5-Minimum → 20K Triangle; 2. Gen-2.5-Extreme-Low → 20K Triangle; 3. Gen-2.5-Low → 20K Triangle. |
| `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. |
| `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/fast?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/fast?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/fast", 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/fast",
      "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/fast",
  "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": 100,
    "usd": "0.10",
    "charged": 100,
    "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](https://doitong.com/developers/models/hyper3d/rodin/v2.5.md) (`hyper3d/rodin/v2.5`): from $0.40 / 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/fast
- 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/fast
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.com/v1/models/hyper3d/rodin/v2.5/fast