Query task
Use the task_id returned by task submission to check status and results. Choose the GET path for the task type and authenticate with Authorization: Bearer <accessToken>. Use data.accessToken from Get token.
Query routes
Append the path below to https://api.hitem3d.ai.
| Task type | GET path | Authorization |
|---|---|---|
| Image to 3D | /open-api/v1/query-task | Bearer <accessToken> |
| Image to Relief | /open-api/v1/depth/query-task | Bearer <accessToken> |
| Image to Embroidery | /open-api/v1/embroidery/query-task | Bearer <accessToken> |
| Texturing | /open-api/v1/query-task | Bearer <accessToken> |
| Model Splitting | /open-api/v1/split/query-task | Bearer <accessToken> |
| Multicolor | /open-api/v1/multicolor/query-task | Bearer <accessToken> |
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
task_id | string | Yes | Task ID returned by the corresponding create endpoint. Pass it in the URL query string. |
Response body
| Field | Type | Description |
|---|---|---|
code | int | Response code. 200 indicates a successful query. |
data.task_id | string | Task ID |
data.state | String | created: Createdqueueing: Queuedprocessing: Processingsuccess: Succeededfailed: Failed |
data.credits_consumed | BigDecimal | Optional. Credits debited for the task minus credits refunded. Returns consumption for successful, queued or processing tasks and 0 for failed tasks.Returns null for historical tasks with no consumption record. |
data.id | string | Result ID |
data.cover_url | string | Cover or preview image URL, valid for one hour. |
data.url | string | Result file URL, valid for one hour. |
msg | string | Response message |
Check code first. If it is one of the generation failure codes listed below, stop polling; data may be empty.
When the query returns normally, check data.state to determine task status. code=200 does not mean generation succeeded.
- Succeeded: Read the result. For model splitting, a character result with joints takes priority when available. Embroidery returns a preview and the selected DST or TBF file.
- Queued or processing: Continue querying the same
task_id. - Failed: Stop polling.
Keep the full download URL. If it expires, query the original task_id again.
Error codes
| Error code | Error message | Description |
|---|---|---|
| 5001001 | generate failed | Generation failed due to a timeout or input parsing failure. Consumed credits have been refunded. |
Request example
This example covers Image to 3D and Texturing. For other tasks, substitute the query path from the table.
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())Response example
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"
}Error example
json
{
"code": 5001001,
"data": {},
"msg": "generate failed"
}