文档中心

影眸 API

创建3D生成任务

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

说明

调用本 API 时，按输出 Token 计费，价格为 0.06 元 / 千 Token。每输出一个 3D 模型固定消耗 3 万 Token（即 1.8 元/次），另有资源包可供选择，详见模型价格。

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

Hyper3d-Gen2

文生 3D：根据您输入文本提示词 + 参数（可选）生成一个 3D 模型文件。

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

快速入口

鉴权说明

体验中心

模型列表

模型计费

API Key

接口文档

常见问题

开通模型

请求参数

跳转响应参数

请求体

model string 必选

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

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

content object[] 必选

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

文生 3D：

文本

文本 + 参数（可选）

图生 3D：

图片

图片 + 文本（可选）

图片 + 参数（可选）

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

信息类型

图片信息 object

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

属性

content. type string 必选

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

content. image_url object 必选

输入给模型的图片对象。

属性

content.image_url. url string 必选

图片信息，可以是图片 URL 或图片 Base64 编码。

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

Base64 编码：请遵循此格式data:image/<图片格式>;base64,<Base64编码>，注意 <图片格式> 需小写，如 data:image/png;base64,{base64_image}。

说明

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

格式支持：jpg、jpeg、png

总像素：小于 4096×4096 px

大小：小于等于 30 MB

最多上传 5 张图片

文本信息 object

输入给模型的文本内容。

属性

content. type string 必选

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

content. text string 必选

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

文本提示词：仅支持英文，长度不超过 400 字符，超过后将截断。

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

seed integer

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

取值范围：[0, 65535] 之间的整数。

注意

相同的请求下，模型收到不同的 seed 值，将生成不同的结果。

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

callback_url string

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

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

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

queued：排队中

running：任务运行中

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

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

模型文本命令（选填）

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

示例

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

用于控制 3D 模型的透明度信息。

true：上传图片的透明部分会被保留，生成的 3D 模型或贴图会按原图的透明轮廓处理。

false：透明部分会被自动填充，可能丢失原始透明效果。

bbox_condition integer[]

指定模型边界的尺寸和缩放因子的数组。该数组包含三个元素，分别是宽度（x轴），高度（y轴）和长度（z轴）。如：

[100,100,100]

说明

如无特殊需求，建议不指定该参数，模型将自行判定边界。

TAPose boolean 默认值 false

生成类人模型时，控制生成的结果是否为T/A Pose。

false：不强制 T/A Pose，由模型自行决定姿态。

true：强制使用标准绑定姿态，并由模型判定是 T-Pose 还是 A-Pose。

subdivisionlevel string 简写 sl

控制 3D 模型的多边形面的数量。可选值：

当 mesh_mode 为 Raw 时，默认值为 high。

high：500k

medium：150k

low：20k

当 mesh_mode 为 Quad 时，默认值为 medium。

high：50k

medium：18k

low：8k

fileformat string 默认值 glb 简写 ff

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

usdz

hd_texture boolean 默认值 false

是否启用 HD 纹理。

true：启用 HD 纹理。

false：不启用 HD 纹理

响应参数

跳转请求参数

id string

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

文生3D

图生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": "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
}'

输出示例

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

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

这个页面对您有帮助吗？

有用

无用

火山方舟