Gen-2 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可选

use_original_alphaboolean可选Default: false

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

preview_renderboolean可选Default: false

响应

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生成

请求时调用参数 'tier=Gen-2' 以使用Gen-2生成模型

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

价格

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

Base Cost: 每次生成消耗 0.5 Credit。
Addons:
- HighPack: 每次生成额外消耗 1 Credit。

请求

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

Authentication

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

Authorization: Bearer RODIN_API_KEY

Body

参数

类型

描述

tier

string

将该参数值设置为Gen-2来调用Gen-2生成模型。必须！默认值为Regular。

images

file/Binary

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

prompt

string

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

use_original_alpha

boolean

默认是false. 如果 True, 上传图像的透明度通道将会直接被用于图片处理。

seed

number

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

geometry_file_format

string

可选的。模型文件的格式。可能的值为glb，usdz，fbx，obj，stl。默认值为glb。

material

string

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

quality

string

可选的。控制生成模型的面数。可选值有high, medium, low, 和extra-low. 当mesh_mode为Raw时: high: 500k, medium: 150k, low: 20k, extra-low: 2k, 默认值为high。当mesh_mode为Quad时: high: 50k, medium: 18k, low: 8k, extra-low: 4k, 默认值为medium。

TAPose

bool

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

bbox_condition

Array of Integer

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

mesh_mode

string

可选的，可选的值有Raw和Quad. 默认值为Quad. Raw模式会生成三角面模型。 Quad模式生成四边面模型。

addons

array of strings

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

preview_renderbool可选的，默认为false. 如果true，生成结束后的下载列表中将会额外多一张高质量渲染图像。

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

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 API的task_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 Gen-2 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=Gen-2" 
unset RODIN_API_KEY

import os
import requests

# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = "your api key"  # Replace with your actual API key
IMAGE_PATH = "/path/to/your/image.jpg"  # Replace with the path to your image

# Read the image file
with open(IMAGE_PATH, 'rb') as image_file:
    image_data = image_file.read()

# Prepare the multipart form data
files = {
    'images': (os.path.basename(IMAGE_PATH), image_data, 'image/jpeg'),
    'tier':(None, 'Gen-2'),
}

# Prepare the headers
headers = {
    'Authorization': f'Bearer {API_KEY}',
}

# Make the POST request
response = requests.post(ENDPOINT, files=files, headers=headers)

# Parse and return the JSON response
print(response.json())

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "mime/multipart"
    "net/http"
    "os"
    "path/filepath"
)

const BaseURI = "https://api.hyper3d.com/api"

type CommonError struct {
    Error   *string `json:"error,omitempty"`
    Message *string `json:"message,omitempty"`
}

type JobSubmissionResponse struct {
    Uuids           []string `json:"uuids"`
    SubscriptionKey string   `json:"subscription_key"`
}

type RodinAllInOneResponse struct {
    CommonError
    Uuid *string                 `json:"uuid,omitempty"`
    Jobs JobSubmissionResponse   `json:"jobs,omitempty"`
}

func RunRodin(token string, filePath string) (*RodinAllInOneResponse, error) {
    var err error
    var buffer bytes.Buffer

    // Create the form data for Rodin API
    writer := multipart.NewWriter(&buffer)

    // Read the image
    image, err := os.ReadFile(filePath)
    if err != nil {
        return nil, err
    }

    // Add the image as a form entry
    fieldWriter, err := writer.CreateFormFile("images", filepath.Base(filePath))
    if err != nil {
        return nil, err
    }

    if _, err = fieldWriter.Write(image); err != nil {
        return nil, err
    }

    err = writer.Close()
    if err != nil {
        return nil, err
    }

    // Set the tier to Rodin Gen-2
    fieldWriter, err = writer.CreateFormField("tier")
    if err != nil {
        return nil, err
    }

    if _, err = fieldWriter.Write([]byte("Gen-2")); err != nil {
        return nil, err
    }

    err = writer.Close()
    if err != nil {
        return nil, err
    }

    // Create the request
    req, err := http.NewRequest("POST", fmt.Sprintf("%s/v2/rodin", BaseURI), &buffer)
    if err != nil {
        return nil, err
    }

    // Set headers
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", writer.FormDataContentType())

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var responseData RodinAllInOneResponse
    err = json.NewDecoder(resp.Body).Decode(&responseData)
    if err != nil {
        return nil, err
    }

    if responseData.Error != nil {
        return nil, fmt.Errorf("%s: %s", *responseData.Error, *responseData.Message)
    }

    return &responseData, nil
}

func main() {
        // Replace with your actual API key
    token := "your api key"
    // Replace with the path to your image
    resp, _ := RunRodin(token, "/path/to/your/image.jpg")
    fmt.Println(resp)
}

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

Minimal Rodin Gen-2 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" \
  -F "tier=Gen-2" 
unset RODIN_API_KEY

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

Minimal Rodin Gen-2 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" \
  -F "tier=Gen-2"
unset RODIN_API_KEY

import os
import requests

# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/rodin"
API_KEY = "your api key"  # Replace with your actual API key
IMAGE_PATH_0 = "/path/to/your/image_0.jpg"  # Replace with the path to your image_0
IMAGE_PATH_1 = "/path/to/your/image_1.jpg"  # Replace with the path to your image_1

# Read the image file
with open(IMAGE_PATH_0, 'rb') as image_file:
    image_data_0 = image_file.read()

with open(IMAGE_PATH_1, 'rb') as image_file:
    image_data_1 = image_file.read()

# Prepare the multipart form data
files = {
    'images': (os.path.basename(IMAGE_PATH_0), image_data_0, 'image/jpeg'),
    'images': (os.path.basename(IMAGE_PATH_1), image_data_1, 'image/jpeg'),
    'tier': (None, 'Gen-2'),
}

# Prepare the headers
headers = {
    'Authorization': f'Bearer {API_KEY}',
}

# Make the POST request
response = requests.post(ENDPOINT, files=files, headers=headers)

# Parse and return the JSON response
print(response.json())

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

Comprehensive Rodin Gen-2 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 "tier=Gen-2" \
  -F "prompt=A 3D model of a futuristic robot" \
  -F "mesh_mode=Raw" \
  -F "mesh_simplify=True" \
  -F "seed=42" \
  -F "geometry_file_format=fbx" \
  -F "material=PBR" \
  -F "quality_override=500000" \
unset RODIN_API_KEY

{
  "error": null,
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "sub-key-1"
  }
}

上一页Overview 下一页Gen-1&1.5 Generation

最后更新于18天前

这有帮助吗？