Check Status

Check the status of a task submitted to the API.

Check the status of a task submitted to the API.

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

subscription_keystringRequired

Responses

201Success

application/json

errorstring · enumOptionalPossible values:

post/api/v2/status

POST /api/v2/status HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 27

{
  "subscription_key": "text"
}

201Success

{
  "error": "OK",
  "jobs": [
    {
      "uuid": "text",
      "status": "Waiting"
    }
  ]
}

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.

Please refrain from calling this API too frequently as it may incur some addtional stress to our servers. We may throttle some requests that are sent too frequently.

Instead, your program can then periodically check the status of the task you submitted by supplying the API endpoint the task subscription key you got from your Generation API call. Once this API tell you that your task has finished, you can safely use the Download API to get a list of URLs from where you can download the result models of your task submitted.

The following table lists the possible values from the API call in the status field and the semantics of them.

Status	Meaning
Waiting	Your task has entered our task queue waiting to be scheduled for execution.
Generating	Our worker is working on generating models for your task.
Done	The task is done. In this case, you can head to the Download API to download the result.
Failed	The task has failed during execution. In this case, you may need to contact our support for details.

Pricing

We do not charge any addtional credits for calling this API to check the status of your task.

Request

Authentication

This API uses bearer key for authentication. You need to include a valid token in the Authorization header for all requests.

Authorization: Bearer RODIN_API_KEY

Body

The API takes one parameter in the POST request body.

Parameter	Type	Description
subscription_key	string	Required. The subscription key of the task you want to query the status of. Typically you will get it in the response from the Generation API.

Response

The JSON response has the following fields.

Property	Type	Description
error	string	Optional. Error message, if any.
jobs	array of objects	The jobs of the task, containing details of individual jobs executed as part of the generation process.
jobs.uuid	string	The uuid of the job.
jobs.status	string	The status of the job. The possible values are summarized in the table above.

Examples

Request with cURL

export RODIN_API_KEY="your api key"
curl -X 'POST' \
  'https://api.hyper3d.com/api/v2/status' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "subscription_key": "your-subscription-key"
}'
unset RODIN_API_KEY

Request with Python 3

import requests
import os

ENDPOINT = "https://api.hyper3d.com/api/v2/status"
API_KEY = os.getenv("HYPER3D_API_KEY")
SUBSCRIPTION_KEY = "your-subscription-key"  # Replace with your actual subscription key

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

# Prepare the JSON payload
data = {
    "subscription_key": SUBSCRIPTION_KEY
}

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

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

Request with Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

const BaseURI = "https://api.hyper3d.com/api"

type CommonError struct {
	Error *string `json:"error,omitempty"`
}

type ApiTaskStatusPair struct {
	Uuid   string `json:"uuid"`
	Status string `json:"status"`
}

type ApiStatusResponse struct {
	CommonError
	Jobs []ApiTaskStatusPair `json:"jobs"`
}

func CheckStatus(token string, subscriptionKey string) (*ApiStatusResponse, error) {
	payload := map[string]string{"subscription_key": subscriptionKey}

	jsonData, err := json.Marshal(payload)
	if err != nil {
		return nil, err
	}

	req, err := http.NewRequest("POST", fmt.Sprintf("%s/v2/status", BaseURI), bytes.NewBuffer(jsonData))
	if err != nil {
		return nil, err
	}

	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var responseData ApiStatusResponse
	err = json.NewDecoder(resp.Body).Decode(&responseData)
	if err != nil {
		return nil, err
	}

	if responseData.Error != nil {
		return nil, fmt.Errorf("error: %s", *responseData.Error)
	}

	return &responseData, nil
}

func main() {
	// Replace with your actual API key
	token := "your api key"
	// Replace with your subscription key
	resp, _ := CheckStatus(token, "your subscription key for a task")
	fmt.Println(resp)
}

Response

{
  "jobs": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "status": "Generating"
    }
  ]
}