Check Status

检查提交给API的任务的执行状态。

Check the status of a task submitted to the API.

post

授权

Authorizationstring必填

Bearer authentication header of the form Bearer <token>.

请求体

subscription_keystring必填

响应

201成功

application/json

errorstring · enum可选可能的值:

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

201成功

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

API生成模型消耗资源和时间，因此我们将其设计为异步的。这意味着你提交了一个生成任务后并不一定能立即得到结果。

请不要过于频繁地调用此API，因为它可能会给我们的服务器带来一些额外的压力。我们可能会限制一些发送过于频繁的请求。

相反的，您可以在程序中向API端点提供您从Generation API call获得的任务的subscription_key来定期检查您提交的任务的状态。当API提示您的任务已经完成，您就可以使用Download API来获取一个Url列表，并在这里下载您的任务生成的模型。

下表列出了API调用中status字段中可能出现的值以及他们的含义。

Status	含义
Waiting	您的任务已经进入我们的任务队列，等待执行生成。
Generating	正在为您的任务生成模型。
Done	任务已经完成，现在您可以使用Download API来下载您的任务结果。
Failed	任务执行失败，您可能需要联系我们的支持团队以了解详情。

价格

我们不会对调用API查询任务进度的行为收取任何额外的费用。

请求

Authentication

此API使用密钥进行身份验证。您需要在所有请求的Authorization头中包含一个有效的密钥.

Authorization: Bearer RODIN_API_KEY

Body

API在POST请求体中需求一个参数。

Parameter	Type	Description
subscription_key	string	Required. 要查询的任务的subscription_key，通常您将从Generation API的响应中得到它。

响应

JSON响应包含以下字段。

Property	Type	Description
error	string	可选。 可能存在的错误信息。
jobs	array of objects	任务的作业，包含作为生成过程的一部分执行的各个作业的详细信息。
jobs.uuid	string	作业的uuid。
jobs.status	string	作业执行状态。可能的状态请参阅上表

样例

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

# Constants
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": [
    "123e4567-e89b-12d3-a456-426614174000": "Generating"
  ]
}