查询状态

查询生成任务的状态。请使用生成响应中 jobs.subscription_key 的值，并避免过于频繁地轮询。

Authorization

bearer

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

subscription_key*string

生成响应中 jobs.subscription_key 返回的任务订阅键。

Response Body

`application/json`

curl -X POST "https://example.com/api/v2/status" \  -H "Content-Type: application/json" \  -d '{    "subscription_key": "your-subscription-key"  }'

{  "error": "NO_SUCH_TASK",  "jobs": [    {      "uuid": "123e4567-e89b-12d3-a456-426614174000",      "status": "Waiting",      "queue_length": 0    }  ],  "message": "string"}

标识选择

此接口需要生成响应中的 jobs.subscription_key。不要传入顶层 uuid，也不要传入 jobs.uuids 中的值。

Job 状态

jobs 中的每个条目都会返回以下四种状态之一：

状态	含义
`Waiting`	排队中，或正在等待依赖的 job。
`Generating`	有 worker 正在执行该 job。
`Done`	该 job 的结果已可下载。
`Failed`	该 job 已停止，不会产出结果。

当 job 处于 Waiting 时，响应中还可能包含 queue_length，表示排在它前面的 job 的大致数量。job 离开队列后该字段会被省略。

示例

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/status' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"subscription_key":"subscription-key-from-generation-response"}'

import os

import requests

api_key = os.environ["RODIN_API_KEY"]
response = requests.post(
    "https://api.hyper3d.com/api/v2/status",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"subscription_key": "subscription-key-from-generation-response"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

func main() {
	body, err := json.Marshal(map[string]string{
		"subscription_key": "subscription-key-from-generation-response",
	})
	if err != nil {
		panic(err)
	}
	req, err := http.NewRequest(http.MethodPost, "https://api.hyper3d.com/api/v2/status", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("RODIN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	client := &http.Client{Timeout: 30 * time.Second}
	response, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	responseBody, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}
	if response.StatusCode >= 400 {
		panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, responseBody))
	}
	fmt.Println(string(responseBody))
}

响应

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

轮询与错误

查询成功返回 HTTP 201。HTTP 400 表示请求体无效，401 表示鉴权缺失或无效，429 表示触发限流。首次查询前等待 5 秒，逐步退避到最长 30 秒，遵循 Retry-After；任一 job 为 Failed 时立即停止，并设置客户端总期限。

201application/json

`application/json`