Get started with Rodin
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
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.
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.
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_KEYReplace 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://api.hyper3d.com/api/v2/rodin \
-H "Authorization: Bearer ${RODIN_API_KEY}" \
-F "images=@/path/to/your/image.jpg"
unset RODIN_API_KEYimport 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)
}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
nullif 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
uuidis 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.
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_KEYimport 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_KEYNext steps
After successfully submitting a task to the Rodin API, here are some recommended next steps to further explore Rodin's capabilities:
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.
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
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.
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.
Last updated
Was this helpful?