面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/shadoweye-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 文件。

模型能力
  • Hyper3d-Gen2
    • 文生 3D：输入文本提示词 + 参数（可选），生成一个 3D 模型文件。
    • 图生 3D：输入图片（1-5张）+文本提示词（可选）+ 参数（可选）生成一个 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 内容的信息，支持文本、图片等类型的元素。

支持以下几种组合：

文生 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}。
type string 必选  |  内容类型

content.type

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

seed integer  |  随机种子

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

取值范围：[0, 65535]

callback_url string  |  回调地址

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

回调返回的 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。
addons string  |  纹理增强

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

  • HighPack：提供 4K 分辨率的纹理贴图。
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 生成任务 查询任务状态；任务成功后，接口通过 file_url 返回生成文件。