# Get started with Rodin

{% hint style="info" %}
**注意：** 您必须拥有商业订阅才能请求此 API。如果您尚未订阅，请[点击此处进行订阅](https://hyperhuman.top/subscribe?utm_source=docs\&utm_medium=none\&utm_campaign=dev-docs-subscribe\&utm_id=dev-docs-outlink)。
{% endhint %}

### Rodin API 的身份验证

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

#### 生成 API 密钥

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

#### **使用 API 密钥进行身份验证**

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

```http
Authorization: Bearer YOUR_RODIN_API_KEY
```

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

### 发起请求

一旦您生成了 API 密钥，就可以使用以下示例代码触发您的第一个请求，以生成高质量的 3D 资产。

{% tabs %}
{% tab title="cURL" %}
```bash
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
```
{% endtab %}

{% tab title="Python 3" %}
{% code fullWidth="false" %}
```python
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())
```
{% endcode %}
{% endtab %}

{% tab title="Go" %}
```go
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)
}
```
{% endtab %}
{% endtabs %}

#### 响应

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

**成功响应示例**

```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-specification/check-status) 和 [下载](../api-specification/download-results) API 节点, 您可以检查已提交作业的状态并下载任务的结果。 **建议您使用状态检查 API 以确保任务准备好下载，如我们在**[**最小示例**](minimal-example) **中演示的，以避免意外结果。**

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

{% tabs %}
{% tab title="cURL" %}
```bash
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
```
{% endtab %}

{% tab title="Python 3" %}
```python
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())
```
{% endtab %}
{% endtabs %}

您将获得如下的 JSON 响应：

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

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

```bash
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 的功能：

1.  **探索可调参数**

    查看我们的[Rodin API 请求规范](../api-specification/rodin-generation)，了解更多用于 3D 资产生成的可调参数。微调您的请求，以通过各种可定制选项实现所需输出。
2. **探索其他 Rodin 生成模型**\
   探索我们其他[可用的 Rodin 生成模型](../api-specification/overview)，以找到最适合您需求的模型。由于默认层级是 Rodin Sketch，请考虑查看其他可能提供额外功能或更适合您项目要求的模型。
3.  **跟踪进度**

    使用我们的 [状态 API ](../api-specification/check-status)跟踪您的 3D 资产生成状态。监控每个作业，确保一切按预期进展。
4.  **检索生成的资产**

    一旦 3D 资产生成完成，请查询我们的 [下载 API](../api-specification/download-results)以打包和下载生成的资产。确保您拥有项目所需的所有文件。
5.  **保持更新**

    关注我们的[Twitter/X](https://x.com/deemostech?lang=en), [Instagram](https://www.instagram.com/deemostechnologies),和 [YouTube](https://www.youtube.com/@DeemosTech) 获取 Rodin Gen-1 和 ChatAvatar 的最新更新。
