文档中心

数美 API

创建3D生成任务

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

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

说明

调用本 API 时，按输出 Token 计费，价格为 0.08 元 / 千 Token，每输出一个 3D 模型花费 5 元至 13 元之间（视生成模式而定），详见模型价格。

模型支持的 3D 生成能力简介

快速入口

鉴权说明

体验中心

模型列表

模型计费

API Key

接口文档

常见问题

开通模型

请求参数

跳转响应参数

请求体

model string 必选

您需要调用的模型的 ID （Model ID），开通模型服务，并查询 Model ID 。

您也可通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费/后付费）、运行状态查询、监控、安全等高级能力，可参考获取 Endpoint ID。

content object[] 必选

输入给模型用于生成 3D 模型文件的信息。目前支持的输入组合：

图生 3D：

图片

图片 + 参数（可选）

信息类型

图片信息 object 必选

输入给模型的图片内容，模型会根据输入的图像生成完整的 3D 模型文件。

属性

content. type string 必选

输入内容的类型，此处应为 image_url。

content. image_url object 必选

输入给模型的图片对象。

属性

content.image_url. url string 必选

图片信息。仅支持图片 URL，请确保图片 URL 可被访问。

说明

传入图片需要满足以下条件：

格式支持：jpg、jpeg、png、webp

大小：小于等于 10 MB

总像素：小于 4096×4096 px

数量：最多上传 4 张图片

文本信息 object

输入给模型的文本内容，当前仅支持传入参数。

属性

content. type string 必选

输入内容的类型，此处应为 text。

content. text string 必选

输入给模型的文本内容。

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

callback_url string

填写本次生成任务结果的回调通知地址。当 3D 生成任务有状态变化时，方舟将向此地址推送 POST 请求。

回调请求内容结构与查询任务API 的返回体一致。

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

queued：排队中

running：任务运行中

succeeded：任务成功（如发送失败，即5秒内没有接收到成功发送的信息，回调三次）

failed：任务失败（如发送失败，即5秒内没有接收到成功发送的信息，回调三次）

模型文本命令(选填)

控制3D文件输出的规格。

示例

resolution string 默认值 1536

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

1536

1536pro

face integer

模型面数，支持自定义配置。取值范围为 [100000, 2000000]。

不同分辨率的推荐面数：

1536：2000000

1536 pro：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 组成，1 表示该位置为有效视图图像；0 表示该位置无对应视图图像。

视图类型按顺序依次为：前视图、后视图、左视图、右视图。

示例：

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

响应参数

跳转请求参数

id string

3D 生成任务 ID 。创建 3D 生成任务为异步接口，获取 ID 后，需要通过查询3D生成任务 API 来查询3D生成任务的状态。任务成功后，会输出生成 3D 的 file_url。

图生3D

输入示例

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://ark-project.tos-cn-beijing.volces.com/doc_3D/cat.png"
            }
        }
    ]
}'

输出示例

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

最近更新时间：2026.08.21 11:18:10

这个页面对您有帮助吗？

有用

无用

火山方舟