# 创建3D生成任务

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks`

本文介绍创建影眸 3D 生成任务 API 的输入输出参数，供您使用接口时查阅字段含义。模型会依据传入的图片信息生成 3D，待生成完成后，您可以按条件查询任务并获取生成的 3D 文件。

> **说明：计费说明**
>
> 调用本 API 时按输出 token 计费，单价为 0.06 元/千 token。每生成一个 3D 模型固定消耗 3 万 token，即 1.8 元/次。另有资源包可供选择，详情请参见 [模型价格](/docs/model-pricing)。

**模型能力**

* **Hyper3d-Gen2**
  * 文生 3D：输入文本提示词 + 参数（可选），生成一个 3D 模型文件。
  * 图生 3D：输入图片（1-5张）+文本提示词（可选）+ 参数（可选）生成一个 3D 模型文件。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**model** `string` `必选` | 模型 ID

您需要调用的模型的 ID（Model ID）。[开通模型服务](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false) 后可 [查询 Model ID](/docs/model-list)。

您也可通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费 / 后付费）、运行状态查询、监控、安全等高级能力，可参考 [获取 Endpoint ID](https://ark.volcengine.com/region:cn-beijing/docs/create-standard-inference-endpoint)。

**content** `object[]` `必选` | 输入内容列表

输入给模型生成 3D 内容的信息，支持文本、图片等类型的元素。

支持以下几种组合：

**文生 3D**

* 纯文本
* 文本 + 参数（可选）

**图生 3D**

* 图片
* 图片 + 文本（可选）
* 图片 + 参数（可选）
* 图片 + 文本（可选）+ 参数（可选）

文本信息 `object`

文本部分，作为生成内容的文本提示词。

**text** `string` `必选` | 文本提示词

`content.text`

输入给模型的文本内容，包括：

* **文本提示词**：仅支持英文，长度不超过 400 字符，超过后将截断。
* **参数（选填）**：通过 --[parameters] 的方式，控制 3D 文件输出的规格，详情见 模型文本命令（选填）。

**type** `string` `必选` | 内容类型

`content.type`

输入内容的类型，此处固定为 `text`。

图片信息 `object`

输入给模型的图片信息。

**image_url** `object` `必选` | 图片对象

`content.image_url`

输入给模型的图片对象。

**url** `string` `必选` | 图片来源

`content.image_url.url`

图片 URL 或图片 Base64 编码。

* **图片 URL**：需确保图片 URL 可被访问。
* **Base64 编码**：需遵循此格式`data:image/<图片格式>;base64,<Base64编码>`，注意 `<图片格式>` 需小写，如 `data:image/png;base64,{base64_image}`。

> **说明：传入图片要求**
>
> * **格式**：`jpg`、`jpeg`、`png`
> * **总像素**：小于 `4096 × 4096` px
> * **大小**：单张图片不超过 30 MB
> * **数量**：最多上传 5 张图片

**type** `string` `必选` | 内容类型

`content.type`

输入内容的类型，此处固定为 `image_url`。

**seed** `integer` | 随机种子

种子整数，用于控制生成内容的随机性。

**取值范围**：`[0, 65535]`

> **注意**
>
> * 相同的请求下，模型收到不同的 `seed` 值，将生成不同的结果。
> * 相同的请求下，模型收到相同的 `seed` 值，会生成类似的结果，但不保证完全一致。

**callback_url** `string` | 回调地址

填写本次生成任务结果的回调通知地址。当 3D 生成任务状态变化时，方舟将向此地址发送 POST 请求，请求内容结构与 [查询 3D 生成任务](/docs/shadoweye-get-3d-generation-task-api) 的响应体一致。

回调返回的 status 包括以下状态：

* queued：排队中
* running：任务运行中
* succeeded： 任务成功（如发送失败，即5秒内没有接收到成功发送的信息，回调三次）
* failed：任务失败（如发送失败，即5秒内没有接收到成功发送的信息，回调三次）

### 模型文本命令参数（选填）

以下参数通过 `content.text` ，以 `--<参数名> <参数值>` 形式传入。

**参数传入方式示例**

```JSON
{
    "content": [
        {
            "type": "text",
            "text": "Complete full-body quadrupedal mech robot, orange and black armored, rounded head with glowing blue sensors, 4 articulated mechanical legs, hard-surface sci-fi design, high-detail joints, photorealistic 8K, fully assembled, no missing parts. --mesh_mode Raw --hd_texture true --material PBR --addons HighPack --quality_override 1000000 --use_original_alpha false --bbox_condition [100,100,100] --TAPose false"
        }
    ]
}
```

**material** `string` `默认值 PBR` | 材质类型

控制 3D 模型的材质类型。可选值：

* `PBR`：物理基础材质，包括基础颜色纹理、金属度纹理、法线纹理和粗糙度纹理，提供高真实感并在动态光照下具有物理准确性。
* `Shaded`：风格化材质，包括基础颜色纹理和烘焙光照。
* `All`：同时生成 PBR 和 Shaded 材质。
* `None`：无纹理，即生成白模。

**mesh_mode** `string` `默认值 Quad` | 网格形状

控制生成模型的网格形状。可选值：

* `Raw`：生成三角面模型。
* `Quad`：生成四边面模型。

**quality_override** `number` | 多边形面数

自定义 3D 模型的多边形面数。不同网格形状对应的取值存在差异：

* 当 `mesh_mode=Raw` 时：取值范围为 `[500, 1000000]`，默认值为 `500000`。
* 当 `mesh_mode=Quad`时：取值范围为 `[1000, 200000]`，默认值为 `18000`。

> **说明**
>
> * `quality_override` 与 `subdivisionlevel` 同时设置时，`subdivisionlevel` 不生效。
> * 建议取值 ≥150000。

**addons** `string` | 纹理增强

增强纹理贴图分辨率。可选值：

* `HighPack`：提供 4K 分辨率的纹理贴图。

> **说明**
>
> 不配置该参数时，默认生成 2K 分辨率的纹理贴图。

**use_original_alpha** `boolean` `默认值 false` | 透明区域处理

是否保留输入图片的透明区域。

* `true`：保留透明区域，生成的 3D 模型或贴图按原图透明轮廓处理。
* `false`：自动填充透明区域，可能丢失原始透明效果。

**bbox_condition** `integer[]` | 模型边界

指定模型边界的宽度、高度和长度，例如 `[100, 100, 100]`。

> **说明**
>
> 如无特殊需求，建议不设置，由模型自动判断边界。

**TAPose** `boolean` `默认值 false` | 标准绑定姿态

生成类人模型时，是否强制使用 T-Pose 或 A-Pose 标准绑定姿态。

* `true`：强制使用标准绑定姿态，由模型判断使用 T-Pose 或 A-Pose。
* `false`：不强制使用标准绑定姿态，由模型自行决定。

**subdivisionlevel** `string` `简写 sl` | 多边形面数等级

控制 3D 模型的多边形面数。不同网格形状对应的取值存在差异：

* 当`mesh_mode=Raw`时，可选值：
  * `high`（默认值）：500k
  * `medium`：150k
  * `low`：20k
* 当`mesh_mode=Quad`时，可选值：
  * `high`：50k
  * `medium`（默认值）：18k
  * `low`：8k

**fileformat** `string` `默认值 glb` `简写 ff` | 文件格式

生成的有纹理 3D 模型文件格式，可选值：

* `glb`
* `obj`
* `usdz`
* `fbx`
* `stl`

**hd_texture** `boolean` `默认值 false` | HD 纹理

是否启用 HD 纹理。

* `true`：启用 HD 纹理。
* `false`：不启用 HD 纹理。

## 响应参数

**id** `string` | 任务 ID

3D 生成任务 ID。仅保存 7 天（从 `created_at` 时间戳开始计算），超时后将自动清除。

创建 3D 生成任务为异步接口。获取 ID 后，需要通过 [查询 3D 生成任务](/docs/shadoweye-get-3d-generation-task-api) 查询任务状态；任务成功后，接口通过 `file_url` 返回生成文件。


## 代码示例

## 文生3D

### cURL


#### Request

```bash
curl -X POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "hyper3d-gen2-260112",
    "content": [
        {
            "type": "text",
            "text": "Complete full-body quadrupedal mech robot, orange and black armored, rounded head with glowing blue sensors, 4 articulated mechanical legs, hard-surface sci-fi design, high-detail joints, photorealistic 8K, fully assembled, no missing parts. --mesh_mode Raw --hd_texture true --material PBR --addons HighPack --quality_override 1000000 --use_original_alpha false --bbox_condition [100,100,100] --TAPose false"
        }
    ],
    "seed": 8648
}'
```

#### Response

```
{
    "id": "cgt-2026******-****",
}
```

## 图生3D

### cURL


#### Request

```bash
curl -X POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "hyper3d-gen2-260112",
    "content": [
        {
            "type": "text",
            "text": "Generate a 3D model from these three reference images showing front, side, and back views"
        },
        {
            "type": "image_url",
            "image_url":  {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/images/domain-models/front_view.png"
                }
        },
        {
            "type": "image_url",
            "image_url":  {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/images/domain-models/side_view.png"
                }
        },
        {
            "type": "image_url",
            "image_url":  {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/images/domain-models/back_view.png"
                }
        }
    ],
    "seed": 8648
}'
```

#### Response

```
{
    "id": "cgt-2026******-****",
}
```