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