# Check Status

{% openapi src="/files/3NCp1UPfaUcBcGXLFv1I" path="/api/v2/status" method="post" %}
[status.yaml](https://563398440-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwiMYwiLTHWAzkgBEpY5K%2Fuploads%2Fgit-blob-0d5da29d98dcbc89a802602efd10a8560426dffb%2Fstatus.yaml?alt=media)
{% endopenapi %}

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

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

相反的，您可以在程序中向API端点提供您从[Generation API call](/zh_cn/api-specification/rodin-generation_reset_v.md)获得的任务的subscription\_key来定期检查您提交的任务的状态。当API提示您的任务已经完成，您就可以使用[Download API](/zh_cn/api-specification/download-results_reset_v.md)来获取一个Url列表，并在这里下载您的任务生成的模型。

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

| Status       | 含义                                                                                           |
| ------------ | -------------------------------------------------------------------------------------------- |
| `Waiting`    | 您的任务已经进入我们的任务队列，等待执行生成。                                                                      |
| `Generating` | 正在为您的任务生成模型。                                                                                 |
| `Done`       | 任务已经完成，现在您可以使用[Download API](/zh_cn/api-specification/download-results_reset_v.md)来下载您的任务结果。 |
| `Failed`     | 任务执行失败，您可能需要联系我们的支持团队以了解详情。                                                                  |

## 价格

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

## 请求

### Authentication

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

```
Authorization: Bearer RODIN_API_KEY
```

### Body

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

| Parameter             | Type       | Description                                                                                                                |
| --------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
| **subscription\_key** | **string** | **Required.** 要查询的任务的subscription\_key，通常您将从[Generation API](/zh_cn/api-specification/rodin-generation_reset_v.md)的响应中得到它。 |

## 响应

JSON响应包含以下字段。

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

## 样例

{% tabs %}
{% tab title="Request with cURL" %}

```sh
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
```

{% endtab %}

{% tab title="Request with Python 3" %}

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

```

{% endtab %}

{% tab title="Request with Go" %}

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

{% endtab %}

{% tab title="Response" %}

```json
{
  "jobs": [
    "123e4567-e89b-12d3-a456-426614174000": "Generating"
  ]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.hyper3d.ai/zh_cn/api-specification/check-status_reset_v.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.