查询任务
提交任务后,用返回的 task_id 查询状态和结果。
按任务类型选择 GET 路径,请求头使用 Authorization: Bearer <accessToken>。令牌取自获取 Token接口返回的 data.accessToken。
查询路径
请求地址为 https://api.hitem3d.ai 加下表路径。
| 任务类型 | GET 路径 | Authorization |
|---|---|---|
| 图生3D | /open-api/v1/query-task | Bearer <accessToken> |
| 图生浮雕 | /open-api/v1/depth/query-task | Bearer <accessToken> |
| 图生刺绣 | /open-api/v1/embroidery/query-task | Bearer <accessToken> |
| 贴图 | /open-api/v1/query-task | Bearer <accessToken> |
| 拆件 | /open-api/v1/split/query-task | Bearer <accessToken> |
| 多色 | /open-api/v1/multicolor/query-task | Bearer <accessToken> |
请求参数
| 参数 | 类型 | 必填 | 参数描述 |
|---|---|---|---|
task_id | string | 是 | 对应创建接口返回的任务 ID,作为 URL 查询参数传入。 |
响应体
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 接口响应码。200 表示查询成功。 |
data.task_id | string | 任务 ID |
data.state | String | created:已创建queueing:排队中processing:处理中success:成功failed:失败 |
data.credits_consumed | BigDecimal | 可选。按任务实际扣减减去已返还积分计算。 成功、排队中或处理中返回消耗积分,失败返回 0。历史任务没有消耗记录时返回 null。 |
data.id | string | 生成物 ID |
data.cover_url | string | 封面或效果图 URL,有效期 1 小时。 |
data.url | string | 结果文件 URL,有效期 1 小时。 |
msg | string | 具体消息 |
先检查响应中的 code。返回下文列出的生成失败码时,停止轮询;此时 data 可能为空。
查询正常返回时,再检查 data.state 判断任务状态;code=200 不代表生成成功。
- 成功:读取结果。拆件若有连接件,优先返回含连接件的结果。刺绣返回指定格式的 DST 或 TBF 文件和效果图。
- 排队或处理中:继续查询同一个
task_id。 - 失败:停止轮询。
下载时保留完整 URL。链接过期后,用原 task_id 重新查询。
错误码
| 错误码 | 错误信息 | 错误描述 |
|---|---|---|
| 5001001 | generate failed | 任务超时或输入解析失败,生成失败;所耗积分已退还。 |
请求示例
以图生3D、贴图为例。查询其他任务时,按表替换查询路径。
bash
curl --get 'https://api.hitem3d.ai/open-api/v1/query-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--data-urlencode "task_id=$HI3D_TASK_ID"python
import os
import requests
response = requests.get(
"https://api.hitem3d.ai/open-api/v1/query-task",
headers={"Authorization": "Bearer " + os.environ["HI3D_TOKEN"]},
params={"task_id": os.environ["HI3D_TASK_ID"]},
)
response.raise_for_status()
print(response.json())响应示例
json
{
"code": 200,
"data": {
"task_id": "<TASK_ID>",
"state": "success",
"credits_consumed": 45,
"id": "<RESULT_ID>",
"url": "<RESULT_URL>",
"cover_url": "<COVER_URL>"
},
"msg": "success"
}错误示例
json
{
"code": 5001001,
"data": {},
"msg": "generate failed"
}