Hi3D

https://docs.hi3d.ai/en/
Admin
Hi3D is an AI-powered image-to-3D generation platform that enables developers and creators to...
Tokens:59,947
Snippets:370
Trust Score:8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Query Task API Python Example

Source: https://docs.hi3d.ai/en/api/api-reference/list/query-task

Python example using the requests library to query a task. Sends a GET request with the required headers and prints the response text.

```python
import requests

url = "https://api.hitem3d.ai/open-api/v1/query-task?task_id=14fb7ecb7b3b467f80cd4bb16e4a44cd.jjewelry-aigc-merchant-api.ZCqTyPcTwV"

payload={}
headers = {
   'Authorization': 'Bearer 6pzBx1a5Cj68XhQe*H07YsrAYSIuSptfihGpHd40QTd3RtfRWy-ao9F12AqYUYdedxmbL0Yl2F8HO9nbhFuIs0hhoaJAd7GUAlgfp2nbHlqTJIBphEHgw_oVAtp9VQtN-mS_uUTwUejcENG4WzwAPtTsJBIZQzGjU_xJzZvnQPPPxaSQaPEBNsekNRFzMLq8us4W3zJJa8P3G0EVnQQ1_jhO6X4ycMBKfqS8GXALZntk-4vkykA4sZxU6edoQEjKGC6oT_dRK3GzevCxI1uvYvwmsNjZYe4G7uDlkNAuny6EdDiBqb3hpf4jETA_mv5ItAJvccd5S91_IJEV0v5uBALrkuD-bDuneLIi2h6-11et4gmAA5_00XgOq8OJDcJ3LUI71Jw==*WeNzV21CwM-cyccZ8BQmfNZn3hViOpTMLg1kJQnb0WI=',
   'Appid': '20009998',
   'User-Agent': 'Apifox/1.0.0 (https://apifox.com)',
   'Accept': '*/*',
   'Host': 'api.hitem3d.ai',
   'Connection': 'keep-alive'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```

--------------------------------

### General Split Request Example (Shell)

Source: https://docs.hi3d.ai/en/api/api-reference/list/split-create-task

Shell example for general split using a mesh URL. Includes model, level, and format parameters.

```shell
curl --location --request POST 'https://api.hitem3d.ai/open-api/v1/split/create-task' \
--header 'Authorization: Bearer {{token}}' \
--form 'mesh_url="https://client.example.com/models/demo.glb"' \
--form 'model="general"' \
--form 'level="medium"' \
--form 'format="2"'
```

--------------------------------

### Query Task API Shell Example

Source: https://docs.hi3d.ai/en/api/api-reference/list/query-task

Shell (curl) example for querying a task. Uses the GET method with the task_id in the URL and includes the required Authorization and Appid headers.

```shell
curl --location --request GET 'https://api.hitem3d.ai/open-api/v1/query-task?task_id=14fb7ecb7b3b467f80cd4bb16e4a44cd.jjewelry-aigc-merchant-api.ZCqTyPcTwV' \
--header 'Authorization: Bearer 6pzBx1a5Cj68XhQe*H07YsrAYSIuSptfihGpHd40QTd3RtfRWy-ao9F12AqYUYdedxmbL0Yl2F8HO9nbhFuIs0hhoaJAd7GUAlgfp2nbHlqTJIBphEHgw_oVAtp9VQtN-mS_uUTwUejcENG4WzwAPtTsJBIZQzGjU_xJzZvnQPPPxaSQaPEBNsekNRFzMLq8us4W3zJJa8P3G0EVnQQ1_jhO6X4ycMBKfqS8GXALZntk-4vkykA4sZxU6edoQEjKGC6oT_dRK3GzevCxI1uvYvwmsNjZYe4G7uDlkNAuny6EdDiBqb3hpf4jETA_mv5ItAJvccd5S91_IJEV0v5uBALrkuD-bDuneLIi2h6-11et4gmAA5_00XgOq8OJDcJ3LUI71Jw==*WeNzV21CwM-cyccZ8BQmfNZn3hViOpTMLg1kJQnb0WI=' \
--header 'Appid: 20009998' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Accept: */*' \
--header 'Host: api.hitem3d.ai' \
--header 'Connection: keep-alive'
```

--------------------------------

### Character Split Request Example (Shell)

Source: https://docs.hi3d.ai/en/api/api-reference/list/split-create-task

Shell example for character split using a local mesh file. Includes model, part, joint, merge, format, and callback_url parameters.

```shell
curl --location --request POST 'https://api.hitem3d.ai/open-api/v1/split/create-task' \
--header 'Authorization: Bearer {{token}}' \
--form 'mesh=@"/path/to/demo.glb"' \
--form 'model="character"' \
--form 'part="a"' \
--form 'joint="ball"' \
--form 'merge="yes"' \
--form 'format="2"' \
--form 'callback_url="https://client.example.com/webhook/split"'
```

--------------------------------

### Create Task API Request Example (Shell)

Source: https://docs.hi3d.ai/en/api/api-reference/list/segmentation-create-task

Shell command to submit a segmentation task. Replace {{token}} with your token and adjust the file path and parameters as needed. The example uses seg_level medium and format 2 (glb).

```shell
curl --location --request POST 'https://api.hitem3d.ai/open-api/v1/segmentation/create-task' \
--header 'Authorization: Token {{token}}' \
--form 'mesh=@"/path/to/demo.glb"' \
--form 'seg_level="medium"' \
--form 'format="2"' \
--form 'callback_url="https://client.example.com/webhook/segmentation"'
```

--------------------------------

### Query Task API - Response Body Example

Source: https://docs.hi3d.ai/en/api/api-reference/list/multicolor-query-task

Example JSON response showing a successful task query with state 'success', artifact ID, cover URL, and model URL.

```json
{
  "code": 200,
  "data": {
    "task_id": "multicolor_20260715_8f92ab3e1cde",
    "state": "success",
    "id": "multicolor_20260715_8f92ab3e1cde_0",
    "cover_url": "https://example.com/cover.png",
    "url": "https://example.com/multicolor/output/result.fbx"
  },
  "msg": "success"
}
```

--------------------------------

### Create depth task with Python requests

Source: https://docs.hi3d.ai/en/api/api-reference/list/depth-create-task

Python example using the requests library to create a depth map task. Sends the image file as multipart form data with the same parameters as the curl example.

```python
import requests

url = "https://api.hitem3d.ai/open-api/v1/depth/create-task"
headers = {"Authorization": "Bearer {{accessToken}}"}
data = {
    "model_type": "base",
    "height_relief": "1.3",
    "format": "6",
    "response_format": "url",
}

with open("/path/to/demo.jpg", "rb") as image:
    response = requests.post(url, headers=headers, data=data, files={"image": image})
response.raise_for_status()
print(response.json())
```

--------------------------------

### Image to 3D All-in-One Generation (Shell)

Source: https://docs.hi3d.ai/en/api/api-reference/list/create-task

Shell example for image-to-3D all-in-one generation (geometry + texture) using the hitem3dv2.0 model. Includes a mesh_url parameter and a callback_url for asynchronous notification. Uses a hardcoded access token and a specific local image path.

```shell
curl --location --request POST 'https://api.hitem3d.ai/open-api/v1/submit-task' \
--header 'Authorization: Bearer 6pzBx1a5Cj68XhQe*H07YsrAYSIuSptfihGpHd40QTd3RtfRWy-ao9F12AqYUYdedxmbL0Yl2F8HO9nbhFuIs0hhoaJAd7GUAlgfp2nbHlqTJIBphEHgw_oVAtp9VQtN-mS_uUTwUejcENG4WzwAPtTsJBIZQzGjU_xJzZvnQPPPxaSQaPEBNsekNRFzMLq8us4W3zJJa8P3G0EVnQQ1_jhO6X4ycMBKfqS8GXALZntk-4vkykA4sZxU6edoQEjKGC6oT_dRK3GzevCxI1uvYvwmsNjZYe4G7uDlkNAuny6EdDiBqb3hpf4jETA_mv5ItAJvccd5S91_IJEV0v5uBALrkuD-bDuneLIi2h6-11et4gmAA5_00XgOq8OJDcJ3LUI71Jw==*WeNzV21CwM-cyccZ8BQmfNZn3hViOpTMLg1kJQnb0WI=' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Accept: */*' \
--header 'Host: api.hitem3d.ai' \
--header 'Connection: keep-alive' \
--header 'Content-Type: multipart/form-data; boundary=--------------------------606514836105993765865977' \
--form 'images=@"/Users/jinyeliu/Desktop/tos_temp/dog.jpeg"' \
--form 'request_type="3"' \
--form 'resolution="512"' \
--form 'face="800000"' \
--form 'mesh_url="https://mm-sparc3d-test.tos-ap-southeast-1.volces.com/jjewelry/web/model3ds/img2model3d/20250724/a483f649a77a4000961e82405bbd4439/target/model/original/0.glb"' \
--form 'model="hitem3dv2.0"' \
--form 'format="2"' \
--form 'callback_url="http://callback.com"'
```

--------------------------------

### Query Task HTTP GET URL

Source: https://docs.hi3d.ai/en/api/api-reference/list/depth-query-task

Example HTTP GET request URL for querying a depth task by task_id. Replace the task_id value with the one returned by the create-task API.

```text
https://api.hitem3d.ai/open-api/v1/depth/query-task?task_id=depth_20260312_8f92ab3e1cde
```

--------------------------------

### Query Task API - Shell Request Example

Source: https://docs.hi3d.ai/en/api/api-reference/list/multicolor-query-task

Curl command to query a task using the GET method with Authorization and Content-Type headers.

```shell
curl --location --request GET 'https://api.hitem3d.ai/open-api/v1/multicolor/query-task?task_id=multicolor_20260715_8f92ab3e1cde' \
--header 'Authorization: Token {{token}}' \
--header 'Content-Type: application/json'
```

--------------------------------

### GET /open-api/v1/multicolor/query-task

Source: https://docs.hi3d.ai/en/api/api-reference/list/multicolor-query-task

This snippet documents the GET endpoint for querying the status and result of a multicolor task.

```APIDOC
## [GET] /open-api/v1/multicolor/query-task

### Description
Queries the current status and result of a 3D model multicolor task by task ID.

### Method
GET

### Endpoint
https://api.hitem3d.ai/open-api/v1/multicolor/query-task

### Parameters
#### Query Parameters
- **task_id** (string) - Required - Task ID returned by the create-task API result.

### Request Example
```
https://api.hitem3d.ai/open-api/v1/multicolor/query-task?task_id=multicolor_20260715_8f92ab3e1cde
```

### Response
#### Success Response (200)
- **code** (int) - Error code, see error code table.
- **data** (object) - Task data.
  - **task_id** (string) - Task ID.
  - **state** (string) - Processing status: `created`, `queueing`, `processing`, `success`, `failed`.
  - **id** (string) - Generated artifact ID.
  - **cover_url** (string) - Generated cover image URL, valid for one hour.
  - **url** (string) - Generated multicolor model URL, valid for one hour.
- **msg** (string) - Detailed error message.

#### Response Example
```json
{
  "code": 200,
  "data": {
    "task_id": "multicolor_20260715_8f92ab3e1cde",
    "state": "success",
    "id": "multicolor_20260715_8f92ab3e1cde_0",
    "cover_url": "https://example.com/cover.png",
    "url": "https://example.com/multicolor/output/result.fbx"
  },
  "msg": "success"
}
```

### Error Codes
| Error Code | Error Message | Error Description |
|------------|---------------|-------------------|
| 5001001 | generate failed | Timeout or model parsing failed. Retry later; credits are refunded |

### Request Example (Shell)
```shell
curl --location --request GET 'https://api.hitem3d.ai/open-api/v1/multicolor/query-task?task_id=multicolor_20260715_8f92ab3e1cde' \
--header 'Authorization: Token {{token}}' \
--header 'Content-Type: application/json'
```
```

--------------------------------

### Balance Query API Shell Request

Source: https://docs.hi3d.ai/en/api/api-reference/list/query-balance

Shell example for querying the account balance. Replace <accessToken> with the access token obtained earlier.

```shell
curl --location --request GET 'https://api.hitem3d.ai/open-api/v1/balance' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json'
```

--------------------------------

### Token Request HTTP Example

Source: https://docs.hi3d.ai/en/api/api-reference/list/get-token

Example HTTP request to obtain a token. The Authorization header uses a Base64-encoded client_id:client_secret string.

```http
POST /open-api/v1/auth/token HTTP/1.1
Host: api.hitem3d.ai
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json
```

--------------------------------

### Create Task Request Example (Shell)

Source: https://docs.hi3d.ai/en/api/api-reference/list/multicolor-create-task

Shell command to submit a multicolor task using curl. Replace {{token}} with your bearer token and adjust the mesh file path and callback URL as needed.

```shell
curl --location --request POST 'https://api.hitem3d.ai/open-api/v1/muilticolor/create-task' \
--header 'Authorization: Bearer {{token}}' \
--form 'mesh=@"/path/to/demo.glb"' \
--form 'model="multicolor"' \
--form 'number_color=4' \
--form 'min_region_faces=50' \
--form 'format=1' \
--form 'callback_url="https://client.example.com/webhook/multicolor"'
```

--------------------------------

### Balance Query API Python Request

Source: https://docs.hi3d.ai/en/api/api-reference/list/query-balance

Python example using the requests library to query the account balance. Replace <accessToken> with the access token obtained earlier.

```python
import requests

url = "https://api.hitem3d.ai/open-api/v1/balance"

payload={}
headers = {
   'Authorization': 'Bearer <accessToken>',
   'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```

--------------------------------

### Token Response Error Example

Source: https://docs.hi3d.ai/en/api/api-reference/list/get-token

Error response example when client credentials are invalid. The HTTP status is still 200 OK, but the code field indicates the error.

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 40010000,
  "message": "client credentials are invalid",
  "data": {}
}
```

--------------------------------

### Image to 3D Staged Generation - Geometry (Python)

Source: https://docs.hi3d.ai/en/api/api-reference/list/create-task

Python example for image-to-3D staged generation (geometry only) using the hitem3dv2.0 model. Sets request_type to "1" and includes a callback_url. Uses a hardcoded access token and a local image file, with error handling and response printing.

```python
import requests

url = "https://api.hitem3d.ai/open-api/v1/submit-task"

headers = {
    "Authorization": "Bearer 6pzBx1a5Cj68XhQe*H07YsrAYSIuSptfihGpHd40QTd3RtfRWy-ao9F12AqYUYdedxmbL0Yl2F8HO9nbhFuIs0hhoaJAd7GUAlgfp2nbHlqTJIBphEHgw_oVAtp9VQtN-mS_uUTwUejcENG4WzwAPtTsJBIZQzGjU_xJzZvnQPPPxaSQaPEBNsekNRFzMLq8us4W3zJJa8P3G0EVnQQ1_jhO6X4ycMBKfqS8GXALZntk-4vkykA4sZxU6edoQEjKGC6oT_dRK3GzevCxI1uvYvwmsNjZYe4G7uDlkNAuny6EdDiBqb3hpf4jETA_mv5ItAJvccd5S91_IJEV0v5uBALrkuD-bDuneLIi2h6-11et4gmAA5_00XgOq8OJDcJ3LUI71Jw==*WeNzV21CwM-cyccZ8BQmfNZn3hViOpTMLg1kJQnb0WI=",
    "User-Agent": "Apifox/1.0.0 (https://apifox.com)",
    "Accept": "*/*",
    "Host": "api.hitem3d.ai",
    "Connection": "keep-alive"
}

files = {
    "images": ("glove_1.jpg", open("/Users/jinyeliu/Desktop/tos_temp/glove_1.jpg", "rb"), "image/jpeg")
}

data = {
    "request_type": "1",
    "resolution": "512",
    "face": "800000",
    "model": "hitem3dv2.0",
    "format": "2",
    "callback_url": "http://callback.com"
}

try:
    response = requests.post(
        url=url,
        headers=headers,
        files=files,
        data=data
    )

    print(f"Status Code: {response.status_code}")
    print(f"Response Content: {response.text}")

except Exception as e:
    print(f"Request Failed: {e}")
```
Tokens:
Raw