Get started with Rodin

Note: You must have a Business subscription to request this API. If you have not yet subscribed, go here to subscribe.

Authentication for Rodin API

Rodin's API uses API keys to authenticate requests. To access Rodin services programmatically, you need to generate an API key. Here’s how to authenticate and use the API keys securely.

Generating an API Key

1. Navigate to the API Key Management Page

   • Log into your Rodin account and go to the API Key Management section.

   • Click on the "+Create new API Keys" button to generate a new key.

2. Store Your API Key Securely

   • Once created, the API key will be displayed only once. Ensure you copy and store it securely. If you lose the key, you will need to generate a new one.

3. Revoke Keys When Necessary

   • You can manage your existing API keys and revoke any that are no longer needed directly from the API Key Management page.

Using the API Key for Authentication

For every API request, include the API key in the Authorization HTTP header. Here’s an example of how to structure your request:

Authorization: Bearer YOUR_RODIN_API_KEY

Replace YOUR_RODIN_API_KEY with the actual API key you generated.

Making requests

Once you’ve generated your API key, you can trigger your first request to generate high-quality 3D assets using the example code provided below.

cURL

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

Python 3

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())

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

Response

When you send a POST request to the Rodin API, the server returns a JSON response. Here is the structure of the response and an explanation of its components.

Example of a Successful Response

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

Fields in the Response

• error: This field will be null if the request is successful. If there is an error, it will contain a string describing the error.

• message: A string message indicating the status of the request. For successful submissions, this will typically be "Submitted."

• uuid: A unique identifier for the task spawned by your request. This uuid is used to track the overall task.

• jobs: An array of job objects. Each job object represents a step in the task and includes:

  • uuids: An array of unique identifiers for the individual jobs. Each job corresponds to a specific process involved in the task, such as model generation or texture generation.

  • subscription_key: A key used to query the status of each job. This key allows you to track the progress and completion of the jobs.

Check Status and Download Results

The Generation APIs are time and resource consuming, so we designed them to be asynchronous. This means that you submit a task without getting the result immediately.

With the Progress Check and Download API endpoint, you can check the status of your submitted job and download results from the task. You are advised to use the Progress Check API to ensure if your task is ready before downloading as we demostrated in the Minimal Example to avoid unexpected results.

As a quick and dirty example in this quick start, we will show you how to get a list of URL to download your results, assuming your task is ready for download.

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}"
}'
unset RODIN_API_KEY

Python 3

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())

You will got an JSON response like the following

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

This is an array of files with a url to download it from and a human-friendly name of the file. You can download them with your browser or with a script programmingly. The following Bash script parses the return with jq and download them with subsequent calls to 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

---

Next steps

After successfully submitting a task to the Rodin API, here are some recommended next steps to further explore Rodin's capabilities:

1. Explore Adjustable Parameters

   Check our Rodin API request specs for more adjustable parameters for 3D asset generation. Fine-tune your requests to achieve the desired output with various customizable options.

2. Explore Other Rodin Generation Models Explore our other available Rodin generation models to find the best fit for your needs. Since the default tier is Rodin Sketch, consider looking into other models that might offer additional features or better suit your project requirements

3. Track Progress

   Use our Status API to track the status of your 3D asset generation. Monitor each job and ensure everything is progressing as expected.

4. Retrieve Generated Assets

   Once the 3D asset generation is complete, query our Download API to package and download the generated assets. Ensure you have all necessary files for your project.

5. Stay Updated

   Follow us on Twitter/X, Instagram, and YouTube for the latest updates on Rodin Gen-1 and ChatAvatar.