面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/shumei-create-3d-generation-task-api.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

创建3D生成任务

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

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

模型能力
  • Hitem3d-2.0
    • 图生 3D：输入图片（ 1-4 张）+文本提示词（可选）+ 参数（可选），生成一个 3D 模型文件。

鉴权#

本接口支持鉴权方式如下，详情请参见 Base URL 及鉴权。

  • API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。

请求参数#

Body 参数#

model string 必选  |  模型 ID

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

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

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 可访问。

type string 必选  |  内容类型

content.type

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

callback_url string  |  回调地址

填写本次生成任务结果的回调通知地址。当 3D 生成任务状态变化时，方舟将向此地址发送 POST 请求，请求内容结构与 查询 3D 生成任务 的响应体一致。

回调返回的 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 生成任务 查询任务状态；任务成功后，接口通过 file_url 返回生成文件。