> For the complete documentation index, see [llms.txt](https://developer.hyper3d.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.hyper3d.ai/zh_cn/api-specification/check-status_reset_v.md).

# 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 %}