Rodin Generation

The all in one API for generating Rodin.

post

This API will generate a mesh and textures for the given images and prompt.

授权
请求体
imagesstring · binary必填
promptstring可选
condition_modestring · enum可选Default: concat可能的值:
seednumber可选
geometry_file_formatstring · enum可选Default: glb可能的值:
materialstring · enum可选Default: PBR可能的值:
qualitystring · enum可选Default: medium可能的值:
quality_overridenumber可选
tierstring · enum可选可能的值:
TAPoseboolean可选Default: false
mesh_modestring · enum可选Default: Quad可能的值:
mesh_simplifyboolean可选Default: true
mesh_smoothboolean可选Default: true
响应
201成功
application/json
post
CLI
curl https://api.hyper3d.com/api/v2/rodin \
--request POST \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Content-Type: multipart/form-data' \
--file 'images=@/path/to/your/image.png' \
--file "tier=Regular" \ 
...
201成功
{
  "error": "text",
  "message": "text",
  "uuid": "text",
  "jobs": {
    "uuids": [
      "text"
    ],
    "subscription_key": "text"
  }
}

Rodin生成

使用此API向我们的服务器提交异步任务。你将从API中获得一个任务UUID,该UUID可用于检查进度下载结果

价格

Note: 参数不会收取任何额外费用,只有模型附加项才会有额外收费。

  • Base Cost: `Sketch`和`Regular`每次生成消耗 0.5 Credit。

  • Addons:

    • HighPack: 每次生成额外消耗 1 Credit。

请求

Note: 所有到这个端点的请求都必须使用multipart/form-data发送,以正确处理文件上传以及网格和纹理生成过程所需的其他参数。

Authentication

此API使用密钥进行身份验证。您需要在所有请求的Authorization头中包含一个有效的密钥. 参阅快速开始获取您的账户的API生成密钥。

Authorization: Bearer RODIN_API_KEY

Body

参数
类型
描述

images

file/Binary

用于图像生成,最多上传5张图片。由于form-data请求将保留图像的顺序,因此将会使用上传列表的第一张图片来生成材质贴图。 对于Image-to-3D模式,图片是必须的。可上传一张或多张图片。(最多上传5张图片。) 对于Text-to-3D模式,则不需要上传图片。

prompt

string

用于指导模型生成的文本提示。 对于Image-to-3D生成模式是可选的。(如果没有提供,将使用基于提供的图像的人工智能生成的提示。) 对Text-to-3D模式是必须的。

condition_mode

string

该参数仅用于多图像生成。 这是一个可选的参数,用于选择多图生成时的生成方式。可能的值为fuseconcat。默认值为concat。 对于fuse 模式,需要上传一张或多张图片。可以融合多张图片的物体特征生成一个模型。 对于concat模式,需要上传同一物体的多张多视角图片,并生成该模型。(无须在意上传图片的顺序。)

seed

number

可选的。网格生成中用于随机化的种子值,范围从0到65535(包括两者)。如果不提供,种子将随机生成。

geometry_file_format

string

可选的。模型文件的格式。可能的值为glbusdzfbxobjstl。默认值为glb

material

string

可选的。材质类型。可能的值为PBRShadedAll。默认值为PBRPBR:物理基础材质,包括基础颜色纹理、金属度纹理、法线纹理和粗糙度纹理,提供高真实感并在动态光照下具有物理准确性。 Shaded:仅包含基础颜色纹理和烘焙光照,提供风格化的视觉效果。 All:会同时生成PBRShaded材质。

quality

string

可选的。生成质量。可能的值为high(50k面), medium(18k面), low(8k面), 和extra-low(4k面)。默认值为medium。 对于Rodin Sketch,该值仅为medium时生效。

quality_override

number

可选的。自定义生成模型的面数。范围从1000到200000面,可对网格面数提供更精确的控制。 该参数为quality参数的进阶参数。当调用该参数时,quality参数不会生效。 对于Rodin Sketch,该参数不会生效,模型面数设置为quality参数的默认值。

tier

string

可选的。默认值为RegularSketch:快速生成,细节较少,适合概念草图或初步构思。 Regular:兼顾速度与质量的生成,适用于大多数场景(默认选项)。 Detail:比 Regular 更丰富的细节表现,适合复杂需求(生成时间更长)。 Smooth:比 Regular 更清晰锐利的输出效果,生成时间略长。

TAPose

bool

可选的。控制生成类人模型时,生成结果展现为T/A Pose。 当该值为true时,生成的模型将为Tpose或者Apose。

bbox_condition

Array of Integer

可选的。该参数是一个控制生成模型最大生成边界的control net. 通常来说,这个数组包含三个元素,分别是宽度(y轴),高度(z轴)和长度(x轴)。

mesh_mode

string

可选的,可选的值有RawQuad. 默认值为Quad. Raw模式会生成三角面模型。 Quad模式生成四边面模型。 当tierSketch:仅生成三角面。

mesh_simplify

bool

可选的。当值为true时,将会生成简化模型。 该参数仅当mesh_mode的值为Raw时生效。

mesh_smooth

bool

可选的。当值为true时,将会生成平滑模型(效果等同于Rodin Gen-1)。 该参数仅当mesh_mode的值为Quad时生效。

addons

array of strings

可选的。生成附加功能。默认为[]。可能的值为HighPack. HighPack选项会提供4K分辨率的纹理贴图而不是基础的2K分辨率,同时还会提供更高面数的模型文件。(约16倍选择quality对应面数。)

Rodin提供两种生成模式: Text-to-3D 和 Image-to-3D. Image-to-3D: 当你将图片文件作为参数上传,Rodin会执行Image-to-3D生成,您可以上传一张或多张图片。当上传多张图片时,

  • fuse模式将融合图片特征来生成模型。

  • concat模式需要您上传同一事物的多张多视角图片用于生成。

Text-to-3D: 当您没有上传任何图片文件,Rodin会执行Text-to-3D生成,您必须上传Prompt参数。

ControlNet: ControlNet通过对生成的输出提供更精细的控制来增强模型定制。它在原始API的基础上添加了几个参数,允许用户操作3D模型的比例、形状和结构等方面。

ControlNet引入以下主要参数,以提供对模型生成过程的高级控制:

  • BoundingBox ControlNet: BoundingBox ControlNet允许用户通过可拖动的边界框指定长度、宽度和高度来定义生成模型的比例。当您希望生成的对象适合特定的尺寸或遵循特定的空间约束时,这尤其有用。

    • 样例:

      {
      "bbox_condition": [
        	100,
        	100,
        	100
        ]
      }
    • bbox_condition: 指定边界框的尺寸和缩放因子的数组。

      • 元素:

        1. Width (Y-axis):100 units.

        2. Height (Z-axis):100 units.

        3. Length (X-axis):100 uints.

      通过设置 bbox_condition,您将指示模型生成一个适合指定尺寸的长方体对象。

    • Bounding Box Axis:

            World               
      
          +z(Height)                                                    
          |                                                
          |                                                        
          |______+y(Width)        
          /                  
         /                      
        /                          
        +x(Length)                        

响应

对于response from the Generation APItask_uuid,使用uuid字段替代jobs_uuid

Property
Type
Description

error

string

错误信息(如有)

message

string

成功信息或详细的错误信息。

uuid

string

生成任务的唯一标识符。

jobs

object

一个作业对象,包含作为生成过程一部分执行的各个作业的详细信息。

jobs.uuids

array of strings

子任务的UUIDs。

jobs.subscription_key

string

任务密钥

代码示例

Minimal Rodin Regular Generation(Image-to-3D)

export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F "images=@/path/to/your/image.jpg"  
unset RODIN_API_KEY

Minimal Rodin Sketch Generation(Image-to-3D)

export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F "images=@/path/to/your/image.jpg" \
  -F "tier=Sketch" 
unset RODIN_API_KEY

Minimal Rodin Generation(Text-to-3D)

export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F "prompt=A 3D model of a futuristic robot" \
unset RODIN_API_KEY

Minimal Rodin Generation(Image-to-3D with multi-view images)

export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F 'condition_mode=concat' \
  -F "images=@/path/to/your/image_0.jpg" \
  -F "images=@/path/to/your/image_1.jpg" 
unset RODIN_API_KEY

Minimal Rodin ControlNet Generation(Bounding Box Condition)

export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F "bbox_condition=[100,100,100]"
  -F "prompt=A sofa."
unset RODIN_API_KEY

Comprehensive Rodin Regular Generation with All Parameters

export RODIN_API_KEY="your api key"
curl https://api.hyper3d.com/api/v2/rodin \
  -H "Authorization: Bearer ${RODIN_API_KEY}" \
  -F "images=@/path/to/your/image.jpg" \
  -F "prompt=A 3D model of a futuristic robot" \
  -F "seed=42" \
  -F "geometry_file_format=fbx" \
  -F "material=PBR" \
  -F "quality=high" \
  -F "use_hyper=true" \
  -F "tier=Regular" \
  -F "addons=HighPack"
unset RODIN_API_KEY

最后更新于

这有帮助吗?