> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 3D 生成介面

> AiHubMix 提供統一的 3D 模型生成 API，支援文生 3D 與圖生 3D，非同步任務模式，首批支援騰訊混元 3D（hy-3d-3.1），產物支援 obj / glb / stl / usdz / fbx 格式與 PBR 材質

## 快速開始

3D 生成是非同步操作，整個流程分為三步：

```text theme={null}
1. 提交任務 → 取得 generation_id
2. 輪詢狀態 → 等待 status 變為 completed
3. 下載產物 → 透過 output 中的 content_url 直接下載 3D 檔案
```

**最簡範例**

```shellscript theme={null}
# 第一步：提交 3D 生成任務（文生 3D）
curl -X POST https://aihubmix.com/v1/3d/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy-3d-3.1",
    "prompt": "一隻戴帽子的柴犬"
  }'

# 回應範例：
# {
#   "id": "eyJtb2RlbCI6Imh5LTNkLTMuMSIsIml...",
#   "object": "3d.generation",
#   "model": "hy-3d-3.1",
#   "status": "queued",
#   "output": null,
#   "error": null,
#   "created_at": 1752728000,
#   "completed_at": null,
#   "expires_at": 1752814400
# }

# 第二步：輪詢查詢狀態（每 10~15 秒查詢一次，直到 status 為 completed）
curl https://aihubmix.com/v1/3d/generations/{generation_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 第三步：下載產物（content_url 為臨時網址，可直接下載，無需認證）
curl "{content_url}" --output model.glb
```

## 介面總覽

| 介面       | 方法   | 路徑                                   | 說明         |
| :------- | :--- | :----------------------------------- | :--------- |
| 建立 3D 任務 | POST | `/v1/3d/generations`                 | 提交 3D 生成任務 |
| 查詢狀態     | GET  | `/v1/3d/generations/{generation_id}` | 查詢任務狀態與產物  |

Base URL：`https://aihubmix.com`

認證方式：Bearer Token

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
```

<Note>
  與影片介面不同，3D 介面**沒有** `/content` 下載端點和 `DELETE` 刪除端點：產物透過查詢回應 `output[]` 中的 `content_url` 直接下載。
</Note>

## 支援的模型

| 廠商 | 模型名稱        | 特點                                       |
| -- | ----------- | ---------------------------------------- |
| 騰訊 | `hy-3d-3.1` | 混元 3D 3.1，支援文生 3D、圖生 3D、草圖生 3D，可選 PBR 材質 |

**生成類型（`generate_type`）**

| 類型         | 說明                     |
| :--------- | :--------------------- |
| `Normal`   | 標準生成（預設），幾何 + 紋理       |
| `Geometry` | 僅生成幾何白模，不含紋理           |
| `Sketch`   | 草圖生 3D，允許同時傳入草圖圖片與文字描述 |

## API 詳細說明

### 請求標頭

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
Content-Type: application/json
```

### 建立 3D 生成任務

```shellscript theme={null}
POST /v1/3d/generations
```

#### **請求主體**

| 參數                 | 類型     | 必填 | 說明                                                                                                                                    |
| :----------------- | :----- | :- | :------------------------------------------------------------------------------------------------------------------------------------ |
| `model`            | string | 是  | 模型名稱：`hy-3d-3.1`                                                                                                                      |
| `prompt`           | string | 條件 | 文字描述，不超過 1024 字元；與 `input_references` 至少傳其一                                                                                           |
| `input_references` | array  | 條件 | 參考圖陣列（圖生 3D），目前僅支援 1 張；項目內 `image_url` 與 `image_base64` 二選一                                                                           |
| `generate_type`    | string | 否  | 生成類型：`Normal`（預設）/ `Geometry` / `Sketch`，不區分大小寫                                                                                       |
| `enable_pbr`       | bool   | 否  | 是否生成 PBR 材質，預設 `false`                                                                                                                |
| `face_count`       | int    | 否  | 目標面數，範圍 `3000` \~ `1500000`；不傳由模型預設決定                                                                                                 |
| `format`           | string | 否  | 產物格式：`stl` / `usdz` / `fbx`，不區分大小寫；不傳時由上游預設決定（Normal 通常回傳 obj + glb，Geometry 僅 glb）；指定格式為**追加**生成（如 `format: "stl"` 回傳 glb + stl，非替換） |
| `extra_body`       | object | 否  | 其餘上游原生參數透傳（見下方說明）                                                                                                                     |

**參數驗證規則**

* `prompt` 與 `input_references` **互斥**（只能傳其一），僅 `generate_type: "Sketch"` 允許兩者同傳（草圖 + 文字描述）。
* `input_references` 每項中 `image_url` 與 `image_base64` 必須**恰好傳一個**：
  * `image_url` 僅支援 `http(s)` 公開 URL，**不支援 data URL**（請改用 `image_base64`）；
  * `image_base64` 解碼後不超過 **6MB**。
* `hy-3d-3.1` 不支援 `LowPoly` 生成類型。
* 請求主體總大小不超過 **10MB**。

<Note>
  **`extra_body` 使用說明**：上游原生參數（如 `polygon_type`）可放入 `extra_body` 頂層透傳。以下參數**必須使用頂層欄位**傳入，出現在 `extra_body` 中會回傳 400：`model`、`prompt`、`image_url`、`image_base64`、`generate_type`、`enable_pbr`、`face_count`、`result_format`；`multi_view_images`（多視角圖）暫不支援。
</Note>

#### 回應範例

```json theme={null}
{
  "id": "eyJtb2RlbCI6Imh5LTNkLTMuMSIsIml...",
  "object": "3d.generation",
  "model": "hy-3d-3.1",
  "status": "queued",
  "output": null,
  "error": null,
  "created_at": 1752728000,
  "completed_at": null,
  "expires_at": 1752814400
}
```

#### 狀態值說明

| 狀態            | 說明                      |
| :------------ | :---------------------- |
| `queued`      | 排隊中                     |
| `in_progress` | 生成中                     |
| `completed`   | 生成完成，`output` 中包含產物下載網址 |
| `failed`      | 生成失敗，`error` 中包含錯誤資訊    |

### 查詢任務狀態

```shellscript theme={null}
GET /v1/3d/generations/{generation_id}
```

輪詢此介面檢查任務是否完成。建議每 **10\~15 秒** 查詢一次。查詢不計費。

#### **回應範例（生成完成）**

```json theme={null}
{
  "id": "eyJtb2RlbCI6Imh5LTNkLTMuMSIsIml...",
  "object": "3d.generation",
  "model": "hy-3d-3.1",
  "status": "completed",
  "output": [
    {
      "type": "obj",
      "b64_json": null,
      "content_url": "https://example-cos.tencentcos.cn/.../model.obj?sign=...",
      "preview_url": "https://example-cos.tencentcos.cn/.../preview.png?sign=..."
    },
    {
      "type": "glb",
      "b64_json": null,
      "content_url": "https://example-cos.tencentcos.cn/.../model.glb?sign=..."
    }
  ],
  "error": null,
  "created_at": 1752728000,
  "completed_at": 1752728180,
  "expires_at": 1752814400
}
```

**`output[]` 欄位說明**

| 欄位            | 說明                                             |
| :------------ | :--------------------------------------------- |
| `type`        | 產物檔案類型（小寫），如 `obj`、`glb`、`stl`                 |
| `b64_json`    | 恆為 `null`（3D 產物不以內嵌方式回傳，統一透過 `content_url` 下載） |
| `content_url` | 產物下載網址（上游臨時連結），**請儘快下載轉存**                     |
| `preview_url` | 預覽縮圖網址（如上游提供）                                  |

<Warning>
  `content_url` 與 `preview_url` 為**臨時連結**，會在一段時間後過期，請在任務完成後儘快下載並轉存到自己的儲存空間。任務 ID 自建立起 **24 小時**內可查詢（`expires_at` 欄位即查詢截止時刻），過期後查詢將回傳錯誤。臨時連結僅支援 GET 請求，HEAD 請求會回傳 403。
</Warning>

## 使用範例

<CodeGroup>
  ```shellscript 文生 3D theme={null}
  curl -X POST https://aihubmix.com/v1/3d/generations \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "hy-3d-3.1",
      "prompt": "一輛復古蒸汽龐克風格的摩托車，黃銅質感，細節豐富",
      "enable_pbr": true
    }'
  ```

  ```shellscript 圖生 3D（URL） theme={null}
  curl -X POST https://aihubmix.com/v1/3d/generations \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "hy-3d-3.1",
      "input_references": [
        { "image_url": "https://example.com/cat.png" }
      ]
    }'
  ```

  ```shellscript 圖生 3D（Base64） theme={null}
  curl -X POST https://aihubmix.com/v1/3d/generations \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "hy-3d-3.1",
      "input_references": [
        { "image_base64": "<BASE64_ENCODED_IMAGE>" }
      ]
    }'
  ```

  ```shellscript 草圖生 3D（Sketch） theme={null}
  curl -X POST https://aihubmix.com/v1/3d/generations \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "hy-3d-3.1",
      "generate_type": "Sketch",
      "prompt": "科幻風格的飛行器，金屬外殼",
      "input_references": [
        { "image_url": "https://example.com/sketch.png" }
      ]
    }'
  ```

  ```shellscript 指定面數與格式 theme={null}
  curl -X POST https://aihubmix.com/v1/3d/generations \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "hy-3d-3.1",
      "prompt": "一個中世紀騎士頭盔",
      "generate_type": "Normal",
      "enable_pbr": true,
      "face_count": 40000,
      "format": "fbx"
    }'
  ```
</CodeGroup>

## 完整呼叫範例

<CodeGroup>
  ```python Python theme={null}
  import requests
  import time

  API_KEY = "AIHUBMIX_API_KEY"
  BASE_URL = "https://aihubmix.com"
  HEADERS = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  # 第一步：建立 3D 生成任務
  response = requests.post(
      f"{BASE_URL}/v1/3d/generations",
      headers=HEADERS,
      json={
          "model": "hy-3d-3.1",
          "prompt": "一隻戴帽子的柴犬",
          "enable_pbr": True
      }
  )
  result = response.json()
  generation_id = result["id"]
  print(f"任務已建立，generation_id: {generation_id}")

  # 第二步：輪詢查詢狀態
  while True:
      status_response = requests.get(
          f"{BASE_URL}/v1/3d/generations/{generation_id}",
          headers=HEADERS
      )
      status_data = status_response.json()
      current_status = status_data["status"]
      print(f"目前狀態: {current_status}")

      if current_status == "completed":
          print("3D 生成完成！")
          break
      elif current_status == "failed":
          error = status_data.get("error") or {}
          print(f"生成失敗: {error.get('message', '未知錯誤')}")
          exit(1)

      time.sleep(15)  # 每 15 秒查詢一次

  # 第三步：下載產物（content_url 為臨時網址，直接下載）
  for item in status_data["output"]:
      file_url = item["content_url"]
      file_name = f"model.{item['type']}"
      file_response = requests.get(file_url)
      with open(file_name, "wb") as f:
          f.write(file_response.content)
      print(f"已儲存 {file_name}（{len(file_response.content) / 1024 / 1024:.1f} MB）")
  ```

  ```javascript Node.js theme={null}
  const API_KEY = "your_aihubmix_api_key";
  const BASE_URL = "https://aihubmix.com";

  async function generate3D() {
    // 第一步：建立任務
    const createResponse = await fetch(`${BASE_URL}/v1/3d/generations`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        model: "hy-3d-3.1",
        prompt: "一隻戴帽子的柴犬",
        enable_pbr: true
      })
    });
    const { id: generationId } = await createResponse.json();
    console.log(`任務已建立: ${generationId}`);

    // 第二步：輪詢狀態
    let result;
    while (true) {
      await new Promise(resolve => setTimeout(resolve, 15000));
      const statusResponse = await fetch(
        `${BASE_URL}/v1/3d/generations/${generationId}`,
        { headers: { "Authorization": `Bearer ${API_KEY}` } }
      );
      result = await statusResponse.json();
      console.log(`目前狀態: ${result.status}`);
      if (result.status === "completed" || result.status === "failed") break;
    }

    if (result.status === "failed") {
      console.error(`生成失敗: ${result.error?.message}`);
      return;
    }

    // 第三步：下載產物
    const fs = require("fs");
    for (const item of result.output) {
      const fileResponse = await fetch(item.content_url);
      const buffer = Buffer.from(await fileResponse.arrayBuffer());
      fs.writeFileSync(`model.${item.type}`, buffer);
      console.log(`已儲存 model.${item.type}`);
    }
  }

  generate3D();
  ```
</CodeGroup>

## 計費說明

* 按**次**計費：價格由 `模型 × generate_type × 是否啟用 PBR × 是否指定面數 × 是否指定格式` 的組合決定，具體價格見[模型廣場](https://aihubmix.com/models)。
* 計費發生在**任務建立成功**時；查詢任務狀態與下載產物不計費。
* 未設定價格的參數組合會在建立時直接回傳 400，不會產生扣費。

## FAQ

### 3D 生成需要多長時間？

通常需要數分鐘，具體取決於模型、生成類型與面數設定。建議以 10\~15 秒的間隔輪詢查詢介面。

### 產物連結和任務的有效期是多久？

* 任務 ID 自建立起 **24 小時**內可查詢，回應中的 `expires_at` 欄位即查詢截止時刻。
* `content_url` / `preview_url` 為上游臨時連結，會在一段時間後過期，請在任務完成後**儘快下載轉存**。

### 可以同時傳 `prompt` 和參考圖嗎？

不可以，兩者互斥——唯一例外是 `generate_type: "Sketch"`（草圖生 3D），允許同時傳入草圖圖片與文字描述。

### `generate_type` 各類型有什麼區別？

| 類型         | 說明                |
| :--------- | :---------------- |
| `Normal`   | 標準生成（幾何 + 紋理），預設值 |
| `Geometry` | 僅幾何白模，無紋理         |
| `Sketch`   | 草圖生 3D，可同傳圖片與文字   |

### 任務失敗怎麼處理？

當 `status` 為 `failed` 時，回應中的 `error` 欄位會包含錯誤資訊：

```json theme={null}
{
  "status": "failed",
  "error": {
    "message": "...",
    "type": "z3d_generation_error"
  }
}
```

常見失敗原因包括：內容違規、圖片格式不支援、參考圖無法存取等。請根據錯誤資訊調整後重試。

***

更新時間：2026-07-17