生成纹理
为上传的 3D 模型生成纹理。
bearerAuthorizationBearer <token>multipart/form-data- body
image*file必填。参考图片，用于指导生成模型贴图，最多上传一张。
binarymodel*file必填。为此模型生成贴图。
binaryprompt?string可选。用于描述所需颜色、材质和表面细节的文字提示。它将与参考图像共同指导纹理生成。
length <= 1024escore?number可选。控制纹理的复杂度和丰富程度。数值越高，纹理越细腻、变化越丰富，材质和色彩表现越强烈；数值越低，纹理则更简洁、简单、扁平。
0 <= value <= 103.5reference_scale?number可选。控制生成的纹理与参考图像的贴合程度。数值越高，纹理在保留颜色、风格和视觉细节方面越接近；数值越低，则提示词和模型拥有更大的自由度。
0.5 <= value <= 11seed?integer可选。用于指导生成的模型的随机种子。
0 <= value <= 65535geometry_file_format?string可选。用于指导生成的模型的几何文件格式。
"glb""glb""usdz""fbx""obj""stl"material?string可选。生成模型的材质。 - `PBR`：基于物理渲染的材质，包含基础色贴图、金属度贴图、法线贴图和粗糙度贴图。 - `Shaded`：包含烘焙光照的基础色贴图。 - `All`：同时包含 PBR 和 Shaded 材质。 - `Hybrid`：带有基础颜色纹理的PBR纹理贴图，其中包含烘焙光照。
"PBR""PBR""Shaded""All""Hybrid"resolution?string"Basic""Basic""High"hd_texture?boolean可选。启用额外的纹理超分辨率和增强处理步骤。这可以提升细节清晰度，但也可能引入伪影。该功能不会决定最终的 2K 或 4K 打包分辨率；
falsetexture_delight?boolean可选。如果为`true`，在生成纹理前会从纹理参考图像中移除高光和烘焙光照，以减少生成材质中的光照伪影。 提示：我们建议将此参数置空或取用默认值，除非您有特殊的光照需求。
falsetexture_mode?string可选。用于指导生成模型贴图的模式。 更高的模式会生成更丰富的纹理细节，但会增加生成时间且可能影响费用，详情看[计费](/zh/api-specification/generate-texture#计费)。 - `legacy`: 旧版纹理模式。 - `extreme-high`: 超高分辨率纹理模式，支持 12K 贴图。详情看[贴图分辨率](/zh/api-specification/generate-texture#贴图分辨率)
"high""legacy""extreme-low""low""medium""high""extreme-high"application/json- response
error?string错误码，当请求无法提交时返回。该字段会随 HTTP 201 一起在响应体中返回，因此客户端必须检查此字段，而不能仅依赖 HTTP 状态码。成功时省略此字段。错误码详细请参考 [errors](/zh/api-specification/errors)。
"NO_SUCH_TASK""ASSET_NOT_AVAILABLE""IMAGE_LABEL_LENGTH_TOO_LONG""INVALID_REQUEST""API_NO_ACTIVE_SUBSCRIPTION""API_SUBSCRIPTION_PLAN_TOO_LOW""API_PARALLELISM_LIMIT_REACHED""API_INSUFFICIENT_FUNDS""API_OBJECT_NOT_FOUND_ON_IMAGE""IMAGE_CONTENT_VIOLATION""PERMISSION_DENIED""API_UNKNOWN"message?string成功消息或详细错误信息。
uuid?string提交的生成任务的唯一标识符。
uuidsubmit_time?string提交任务的服务器时间。
date-timejobs?一个包含生成过程中执行的各个任务详细信息的工作对象。
consumed?number本次请求消耗的 credits。
curl -X POST 'https://api.hyper3d.com/api/v2/rodin_texture_only' \ -F 'image=string' \ -F 'model=string'{ "error": "NO_SUCH_TASK", "message": "Submitted.", "uuid": "123e4567-e89b-12d3-a456-426614174000", "submit_time": "2019-08-24T14:15:22Z", "jobs": { "uuids": [ "52faea01-729e-4195-85e8-6050a65315e3" ], "subscription_key": "string" }, "consumed": 0.5}输入
通过 multipart 上传恰好一张参考图片和恰好一个 3D 模型，两者都是必填项。
图片支持 JPEG、PNG、WebP、TIFF、GIF、AVIF、HEIC、HEIF、BMP 和 JPEG 2000；模型支持 OBJ、STL、glTF/GLB、FBX 和 USDZ。
material 可取 PBR、Shaded 或 All，默认为 PBR；All 会同时交付 PBR 和 Shaded 输出。resolution 可取 Basic（2K）或 High（4K），默认为 Basic。
示例
curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rodin_texture_only' \
--header "Authorization: Bearer ${RODIN_API_KEY}" \
--form 'image=@./reference.png' \
--form 'model=@./model.glb' \
--form 'material=PBR' \
--form 'resolution=Basic'
贴图分辨率
贴图分辨率由 texture_mode 和 resolution 决定。
| texture_mode | resolution | Output resolution |
|---|---|---|
| legacy, extreme-low, low, medium, high | Basic | 2K |
| High | 4K | |
| extreme-high | Basic | 6K |
| High | 12K |
计费
| 项目 | 收费 |
|---|---|
| 基础贴图生成 | 0.5 credits |
texture_mode=extreme-high | 2.0 credits |
响应与错误
提交成功后的标识规则与 Rodin 生成一致：用 jobs.subscription_key 查询状态，用顶层 uuid 下载结果。
{
"message": "Submitted.",
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"jobs": {
"uuids": ["223e4567-e89b-12d3-a456-426614174000"],
"subscription_key": "subscription-key-from-generation-response"
},
"consumed": 0.5
}
HTTP 201 仅表示 endpoint 已处理请求；只有在 error 缺失或为空且顶层 uuid 非空时，任务才算已受理。HTTP 400 表示字段或文件无效，401 表示鉴权无效，429 表示触发限流。