# 创建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.08 元/千 token。每生成一个 3D 模型的费用为 5 元至 13 元，具体费用取决于生成模式。详情请参见 [模型价格](/docs/model-pricing)。

**模型能力**

* **Hitem3d-2.0**
  * 图生 3D：输入图片（ 1-4 张）+文本提示词（可选）+ 参数（可选），生成一个 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](/docs/online-inference-standard)。

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

输入给模型生成 3D 内容的信息，支持图片和模型文本命令。

支持以下几种组合：

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

文本信息 `object`

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

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

`content.text`

输入给模型的模型文本命令，仅支持输入参数。

* **参数（选填）**：通过 --[parameters] 的方式，控制 3D 文件输出的规格，详情见 模型文本命令（选填）。

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

`content.type`

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

图片信息 `object`

输入给模型的图片信息。

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

`content.image_url`

输入给模型的图片对象。

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

`content.image_url.url`

图片 URL。请确保图片 URL 可访问。

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

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

`content.type`

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

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

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

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

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

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

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

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

```JSON
{
    "content": [
        {
            "type": "text",
            "text": "--resolution 1536 --request_type 3 --ff 1 --face 2000000"

        }
    ]
}
```

**resolution** `string` `默认值 1536` | 模型分辨率

控制 3D 模型的分辨率。可选值：

* `1536`
* `1536pro`

**face** `integer` | 模型面数

自定义模型面数，取值范围为 `[100000, 2000000]`。

`1536` 和 `1536pro` 分辨率均推荐设置为 `2000000`。

**fileformat** `integer` `默认值 1` `简写 ff` | 文件格式

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

* `1`：对应的文件格式为 obj
* `2`：对应的文件格式为 glb
* `3`：对应的文件格式为 stl
* `4`：对应的文件格式为 fbx
* `5`：对应的文件格式为 usdz

**request_type** `integer` `默认值 3` | 请求类型

请求类型。可选值：

* `1`：仅生成纯几何模型。
* `3`：一次生成几何和纹理模型。

**multi_images_bit** `string` | 多视图位图标识

上传图像数组的位图标识，用于标记 `content.image_url` 中各图像的视图类型。字符串由 `0` 和 `1` 组成，视图顺序依次为前视图、后视图、左视图、右视图。

| 参数值 | 含义 | 数组内容顺序 |
| --- | --- | --- |
| `1010` | 存在前视图、左视图 | `[前视图, 左视图]` |
| `1011` | 存在前视图、左视图、右视图 | `[前视图, 左视图, 右视图]` |
| `1111` | 四个视图均存在 | `[前视图, 后视图, 左视图, 右视图]` |
| `0101` | 存在后视图、右视图 | `[后视图, 右视图]` |

## 响应参数

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

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

创建 3D 生成任务为异步接口。获取 ID 后，需要通过 [查询 3D 生成任务](/docs/shumei-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": "hitem3d-2-0-251223",
    "content": [
        {
            "type": "text",
            "text": "--ff 2 --resolution 1536pro"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://arkdocs.tos-cn-beijing.volces.com/images/domain-models/cat.png"
            }
        }
    ]
}'
```

#### Response

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