帮你快速理解、总结文档立即下载

Rodin-Gen-3D-2.5 调用指南

最近更新时间:2026-11-13 10:57:00
本文档已由 AI 辅助审校
我的收藏

简介

rodin-gen-3d-2.5接口,根据输入的图片或文本智能生成高质量3D 模型。

对接说明

1. 获取 API Key

1. 进入 API Key 管理 页面,单击创建 API Key。操作详情请参见 创建 API Key。
2. 创建完成后,请您务必复制并妥善保管 API Key,在后续配置到工具的流程中将会使用该信息。

说明:
每个账户的密钥都只能当前账户查询,主账户的密钥信息子账户是看不到,子账户如果需要调用接口,需要使用账户自行创建密钥信息。
如果子账户没有办法创建,可能是没有权限创建密钥,需要主账户授权,主账户登录之后点击用户列表,在对应的子账户后面选择授权,会弹出关联策略的弹窗,输入授权策略名称之后搜索,选择对应的策略点击确认。
授权策略:QcloudTokenhubFullAccess

2. 并发额度

默认提供 3 个并发,代表最多可同时处理 3 个已提交的任务,超出并发限制的任务需等待前面的任务处理完成后才能开始处理。
并发任务数:表示在调用对应服务的时段内最大可运行的任务数,该任务未完成时,无法提交下一个任务,该任务完成后,可提交下一个任务。

接口文档

提交3D 生成任务

输入参数
参数名称
必选
类型
参数描述
model
是
string
模型名称。默认为 rodin-gen-3d-2.5。示例值:rodin-gen-3d-2.5
prompt
条件必选
string
文本描述,文生3D 时必填,最大1024字符。与 images 严格互斥,不能同时传递。
images
条件必选
array<string>
图片 URL 数组,图生3D 时必填,1~5张。支持 jpeg/jpg/png/webp,单张图片大小不超过 100MB,图片总大小无限制。与 prompt 严格互斥。
tier
是
string
模型档位。可选:Gen-2.5-Extreme-Low、Gen-2.5-Low、Gen-2.5-Medium、Gen-2.5-High、Gen-2.5-Extreme-High。
mesh_mode
否
string
网格拓扑模式。可选 Raw(三角面,默认)或 Quad(四边面)。
quality
否
string
网格质量预设。可选 extra-low、low、medium(默认)、high。
quality_override
否
int
自定义目标面数,范围500~2000000;设置后优先于 quality。
texture_mode
否
string
纹理模式。可选 legacy、extreme-low、low、medium、high、extreme-high;默认值取决于 tier。
material
否
string
材质类型。可选 PBR(默认)、Shaded、All、Hybrid、None。
geometry_file_format
否
string
输出文件格式。可选 glb(默认)、usdz、fbx、obj、stl。
seed
否
int
随机种子,范围0~65535。
soft
否
bool
是否平滑边缘,默认 false。
detail_level
否
int
几何优化阶段数量,范围1~3。
quad_normal
否
bool
是否将高分辨率几何细节烘焙为法线贴图,默认 false。
bbox_condition
否
array<int>
控制最大尺寸 (x, y, z),需提供3个整数。
addons
否
array<string>
附加项,如 HighPack(将 pack 纹理由2K 提升至4K)。
TAPose
否
bool
类人模型是否使用 T/A-pose,默认 false。
use_original_alpha
否
bool
是否使用原始 alpha 通道,默认 false。
preview_render
否
bool
是否生成预览渲染图,默认 false。
is_symmetric
否
string
对称性。可选 symmetric、balanced、asymmetric、unknown(默认)。
image_label
否
array<string>
图像方向标签。可选 F、FL、FR、B、BL、BR、L、R、U、D、?。
hd_texture
否
bool
是否启用纹理超分辨率增强,默认 false。
uhd_texture
否
bool
是否启用纹理额外锐化,默认 false。
is_micro
否
bool
是否启用微小表面细节,仅 Gen-2.5-Extreme-High 有效,默认 false。
geometry_instruct_mode
否
string
几何策略。可选 creative(默认,更灵活)或 faithful(更忠实)。
texture_delight
否
bool
是否移除参考图像中的高光和烘焙光照,默认 false。
输出参数
参数名称
类型
描述
id
string
任务 ID,有效期24小时,用于查询任务状态。
示例值:1315932989749215232
object
string
返回对象类型,3D 任务固定为 3d_job。
created_at
int
任务创建时间(Unix 时间戳)。
status
string
任务状态。提交成功时为 queued。
request_id
string
请求追踪 ID,用于定位问题。

查询3D 生成任务

输入参数
参数名称
必选
类型
参数描述
model
是
string
模型名称。默认为 rodin-gen-3d-2.5。
示例值:rodin-gen-3d-2.5
id
是
string
提交接口返回的任务 ID。
示例值:1315932989749215232
输出参数
参数名称
类型
描述
request_id
string
请求追踪 ID,用于定位问题。
object
string
返回对象类型,3D 任务固定为 3d_job。
created_at
int
任务创建时间(Unix 时间戳)。
status
string
任务状态:queued(等待中)、in_progress(执行中)、completed(任务成功)、failed(任务失败)。
data
array
生成结果文件列表,仅 completed 状态返回。
data[n].name
string
文件名称,如 model.glb。
data[n].url
string
文件下载 URL,有效期1天。
error
object
错误信息,仅 failed 状态返回。
error.code
string
错误码。
error.message
string
错误信息。
error.type
string
错误类型。

示例

提交3D 生成任务

输入示例
curl --location --request POST 'https://tokenhub.tencentmaas.com/v1/api/3d/submit' \\
--header "Authorization: Bearer ${APIKEY}" \\
--header 'Content-Type: application/json' \\
--data-raw '{
"model": "rodin-gen-3d-2.5",
"tier": "Gen-2.5-Medium",
"images": [
"https://example.com/input.png"
]
}'
输出示例
{
"created_at": 1791431478,
"id": "<JOB_ID>",
"object": "3d_job",
"request_id": "<REQUEST_ID>",
"status": "queued"
}

查询3D 生成任务

输入示例
curl --location --request POST 'https://tokenhub.tencentmaas.com/v1/api/3d/query' \\
--header "Authorization: Bearer ${APIKEY}" \\
--header 'Content-Type: application/json' \\
--data-raw '{
"model": "rodin-gen-3d-2.5",
"id": "<JOB_ID>"
}'
输出示例
{
"created_at": 1791431598,
"data": [
{
"name": "base_basic_pbr.glb",
"url": "https://example.com/base_basic_pbr.glb"
},
{
"name": "preview.webp",
"url": "https://example.com/preview.webp"
}
],
"object": "3d_job",
"request_id": "<REQUEST_ID>",
"status": "completed"
}

错误码

错误码
说明
InvalidParameter.InvalidParameter
请求参数不合法。
InvalidParameter.InputRequired
images 和 prompt 必填其一。
InvalidParameter.InputConflict
images 和 prompt 不能同时存在。
InvalidParameter.TierNotValid
tier 取值不在合法范围内。
InvalidParameter.ImagesExceedsLimit
图片数量超限,最多5张。
InvalidParameter.PromptTooLong
prompt 文本长度超限。
InvalidParameter.FileTypeNotSupported
图片中未检测到有效对象。
RequestLimitExceeded.JobNumExceed
API 并发限制已达上限。
FailedOperation.ModerationFailed
图片内容违规,审核不通过。
FailedOperation.ImageSizeExceed
图片标签数量超出限制。
FailedOperation.InnerError
内部服务错误,包括任务不存在、原厂未知错误、订阅过期或权限不足等情况。
FailedOperation.ServerError
算法服务异常。