Get started with Rodin

注意： 您必须拥有商业订阅才能请求此 API。如果您尚未订阅，请点击此处进行订阅。

Rodin API 的身份验证

Rodin 的 API 使用 API 密钥来验证请求。要以编程方式访问 Rodin 服务，您需要生成一个 API 密钥。以下是如何安全地进行身份验证和使用 API 密钥的步骤。

生成 API 密钥

导航到 API 密钥管理页面
- 登录到您的 Rodin 账户，进入 API 密钥管理部分。
- 点击“+创建新 API 密钥”按钮以生成新密钥。
安全存储您的 API 密钥
- 一旦创建，API 密钥将仅显示一次。确保您复制并安全存储。如果您丢失了密钥，您需要生成一个新密钥。
在必要时撤销密钥
- 您可以直接在 API 密钥管理页面管理现有的 API 密钥，并撤销不再需要的密钥。

使用 API 密钥进行身份验证

对于每个 API 请求，请在 Authorization HTTP 头中包含 API 密钥。以下是如何构建请求的示例：

Authorization: Bearer YOUR_RODIN_API_KEY

将 YOUR_RODIN_API_KEY 替换为您实际生成的 API 密钥。

发起请求

一旦您生成了 API 密钥，就可以使用以下示例代码触发您的第一个请求，以生成高质量的 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

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')
}

# 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
	}

	// 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)
}

响应

当您向 Rodin API 发送 POST 请求时，服务器会返回一个 JSON 响应。以下是响应的结构及其组成部分的解释。

成功响应示例

{
  "error": null,
  "message": "Submitted.",
  "uuid": "example-task-uuid",
  "jobs": {
      "uuids": ["job-uuid-1", "job-uuid-2"],
      "subscription_key": "example-subscription-key"
  }
}

响应中的字段

error: 如果请求成功，此字段将为 null。如果出现错误，则会包含描述错误的字符串。
message: 表示请求状态的字符串消息。对于成功的提交，这通常为 "Submitted."。
uuid: 您请求生成的任务的唯一标识符。此 uuid 用于跟踪整体任务。
jobs: 作业对象的数组。每个作业对象表示任务中的一个步骤，包括：
- uuids: 每个作业的唯一标识符数组。每个作业对应于任务中的特定过程，例如模型生成或纹理生成。
- subscription_key: 用于查询每个作业状态的密钥。此密钥允许您跟踪作业的进度和完成情况。

检查状态和下载结果

生成 API 是耗时且资源密集型的，因此我们将其设计为异步。这意味着您提交一个任务后不会立即获得结果。

通过状态检查和下载 API 节点, 您可以检查已提交作业的状态并下载任务的结果。 建议您使用状态检查 API 以确保任务准备好下载，如我们在最小示例 中演示的，以避免意外结果。

作为一个快速示例，我们将展示如何获取下载结果的 URL 列表，假设您的任务已经准备好下载。

export RODIN_API_KEY="your api key"
curl -X 'POST' \
  'https://api.hyper3d.com/api/v2/download' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "task_uuid": "{REPLACE TASK UUID YOU GOT FROM LAST STEP}"
}'
unset RODIN_API_KEY

import requests

# Constants
ENDPOINT = "https://api.hyper3d.com/api/v2/download"
API_KEY = "your api key"  # Replace with your actual API key
TASK_UUID = "your-task-uuid"  # Replace with your actual task UUID

# Prepare the headers
headers = {
    'accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {API_KEY}',
}

# Prepare the JSON payload
data = {
    "task_uuid": TASK_UUID
}

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

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

您将获得如下的 JSON 响应：

{
  "list": [
    {
      "url": "https://example.com/",
      "name": "test-file"
    }
  ]
}

这是一个包含文件的数组，每个文件都有一个 url 用于下载，以及一个用户友好的 name。您可以使用浏览器或通过脚本程序下载这些文件。以下是一个 Bash 脚本示例，它使用 jq 解析返回结果，并通过后续调用 curl 下载文件。

export RODIN_API_KEY="your api key"

curl -X 'POST' \
  'https://api.hyper3d.com/api/v2/download' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "task_uuid": "{REPLACE TASK UUID YOU GOT FROM LAST STEP}"
}' | \
   jq -r '.list[] | "\(.url) \(.name)"' | \
   while read url name; do
     curl -o "$name" "$url"
   done

unset RODIN_API_KEY

后续步骤

在成功提交任务到 Rodin API 后，以下是一些推荐的后续步骤，以进一步探索 Rodin 的功能：

探索可调参数
查看我们的Rodin API 请求规范，了解更多用于 3D 资产生成的可调参数。微调您的请求，以通过各种可定制选项实现所需输出。
探索其他 Rodin 生成模型 探索我们其他可用的 Rodin 生成模型，以找到最适合您需求的模型。由于默认层级是 Rodin Sketch，请考虑查看其他可能提供额外功能或更适合您项目要求的模型。
跟踪进度
使用我们的状态 API 跟踪您的 3D 资产生成状态。监控每个作业，确保一切按预期进展。
检索生成的资产
一旦 3D 资产生成完成，请查询我们的下载 API以打包和下载生成的资产。确保您拥有项目所需的所有文件。
保持更新
关注我们的Twitter/X, Instagram,和 YouTube 获取 Rodin Gen-1 和 ChatAvatar 的最新更新。

下一页Minimal Example

最后更新于4个月前

这有帮助吗？