Hyper3D API Documentation
DashboardLoginStart For Free
English
English
  • Introduction
  • GET STARTED
    • Get started with Rodin
    • Minimal Example
  • API Specification
    • Overview
    • Rodin Generation
    • Check Balance
    • Check Status
    • Download Results
    • Generate Texture
  • Legal
    • Data Retention Policy
      • Privacy Policy
      • Terms of Service
      • Contact Us
Powered by GitBook
On this page
  • Authentication for Rodin API
  • Making requests
  • Check Status and Download Results
  • Next steps

Was this helpful?

  1. GET STARTED

Get started with Rodin

PreviousIntroductionNextMinimal Example

Last updated 9 months ago

Was this helpful?

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

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.

export RODIN_API_KEY="your api key"
curl https://hyperhuman.deemos.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://hyperhuman.deemos.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://hyperhuman.deemos.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.

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.

export RODIN_API_KEY="your api key"
curl -X 'POST' \
  'https://hyperhuman.deemos.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://hyperhuman.deemos.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://hyperhuman.deemos.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

  2. Track Progress

  3. Retrieve Generated Assets

  4. Stay Updated

With the and 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 to avoid unexpected results.

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

Explore Other Rodin Generation Models Explore our other 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

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

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

Follow us on , , and for the latest updates on Rodin Gen-1 and ChatAvatar.

go here to subscribe
Progress Check
Download
Minimal Example
Rodin API request specs
available Rodin generation models
Status API
Download API
Twitter/X
Instagram
YouTube