Quickstart
Hi3D API generates 3D models from images. Tasks are asynchronous: keep the returned task_id, query until success, then download the result.
| Parameter | Value |
|---|---|
| Base URL | https://api.hitem3d.ai |
| Authorization | Basic for token exchange, Bearer for API calls |
| Protocol / response | HTTPS / application/json |
Before you start
- Sign in and activate a trial package or purchase credits.
- Create and enable an API key to obtain an Access Key and Secret Key. The Secret Key appears only at creation.
- Store the keys in the server-side environment variables
HI3D_ACCESS_KEYandHI3D_SECRET_KEY. Keep the keys out of frontend code.
Authentication
- Use your Access Key and Secret Key with
Basicauthentication to call Get token. Readdata.accessTokenfrom the response. - For task submission, task queries, and balance queries, send
Authorization: Bearer <accessToken>. Replace<accessToken>with the value from step 1.
The API keys are used for token exchange. Subsequent calls send the access token, reducing exposure of the Secret Key in API requests.
1. Get a token
curl --request POST 'https://api.hitem3d.ai/open-api/v1/auth/token' \
--user "$HI3D_ACCESS_KEY:$HI3D_SECRET_KEY" \
--header 'Content-Type: application/json'import os
import requests
response = requests.post(
"https://api.hitem3d.ai/open-api/v1/auth/token",
auth=(os.environ["HI3D_ACCESS_KEY"], os.environ["HI3D_SECRET_KEY"]),
headers={"Content-Type": "application/json"},
)
response.raise_for_status()
print(response.json())Check the business response, then save data.accessToken as HI3D_TOKEN. An HTTP success alone does not guarantee business success.
{
"code": 200,
"data": {
"accessToken": "<TOKEN>",
"tokenType": "Bearer",
"nonce": "<NONCE>"
}
}2. Create a task
This example uses hi3dv3.0, 2048quality, geometry + texture, PBR on and GLB output. Replace input.png with a local image. This configuration costs 45 credits; see Model pricing for details.
curl --request POST 'https://api.hitem3d.ai/open-api/v1/submit-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--form 'images=@./input.png' \
--form 'request_type=3' \
--form 'model=hi3dv3.0' \
--form 'resolution=2048quality' \
--form 'format=2' \
--form 'pbr=1'import os
import requests
data = {
"request_type": "3",
"model": "hi3dv3.0",
"resolution": "2048quality",
"format": "2",
"pbr": "1",
}
with open("input.png", "rb") as file_0:
files = [
("images", ("input.png", file_0)),
]
response = requests.post(
"https://api.hitem3d.ai/open-api/v1/submit-task",
headers={"Authorization": "Bearer " + os.environ["HI3D_TOKEN"]},
data=data,
files=files,
)
response.raise_for_status()
print(response.json()){
"code": 200,
"data": {
"task_id": "<TASK_ID>"
},
"msg": "success"
}Save data.task_id as HI3D_TASK_ID. Acceptance does not mean generation has finished.
3. Check task status
curl --get 'https://api.hitem3d.ai/open-api/v1/query-task' \
--header "Authorization: Bearer $HI3D_TOKEN" \
--data-urlencode "task_id=$HI3D_TASK_ID"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())Query the same task_id and check data.state.
created,queueing, orprocessing: wait and query again.success: readdata.url.failed: stop polling and inspect the error.
Set the polling interval according to your application and server limits. See Async tasks & results.
{
"code": 200,
"data": {
"task_id": "<TASK_ID>",
"state": "success",
"id": "<RESULT_ID>",
"url": "<RESULT_URL>",
"cover_url": "<COVER_URL>"
},
"msg": "success"
}4. Download the result
Save data.url from a successful response as HI3D_RESULT_URL. Result and cover links are valid for one hour. Save the files promptly.
curl --fail --location "$HI3D_RESULT_URL" --output model.glbimport os
import requests
response = requests.get(os.environ["HI3D_RESULT_URL"])
response.raise_for_status()
with open("model.glb", "wb") as output:
output.write(response.content)Replace angle-bracket placeholders with actual response values. Examples do not execute automatically on this page.
Full API reference → · Asynchronous process → · Task records and export
Complete Python example
Install requests with pip install requests, set HI3D_ACCESS_KEY and HI3D_SECRET_KEY, and prepare input.png in the current directory. This example authenticates, creates a task, polls and downloads the result, while saving the task ID locally.
Polling and wait limits are client-side example settings, not server limits or an SLA. If the client stops waiting, query the saved task ID instead of rerunning task creation.
import os
import time
from pathlib import Path
import requests
BASE_URL = "https://api.hitem3d.ai"
# Client-side example settings, not server limits or a service SLA.
POLL_INTERVAL = 5
POLL_WAIT_SECONDS = 600
def checked(response):
response.raise_for_status()
payload = response.json()
if str(payload.get("code")) != "200":
raise RuntimeError(payload.get("msg") or payload.get("message") or payload)
return payload["data"]
token = checked(requests.post(
BASE_URL + "/open-api/v1/auth/token",
auth=(os.environ["HI3D_ACCESS_KEY"], os.environ["HI3D_SECRET_KEY"]),
headers={"Content-Type": "application/json"},
timeout=30,
))["accessToken"]
headers = {"Authorization": "Bearer " + token}
with open("input.png", "rb") as image:
task = checked(requests.post(
BASE_URL + "/open-api/v1/submit-task",
headers=headers,
data={"request_type": "3", "model": "hi3dv3.0",
"resolution": "2048quality", "format": "2", "pbr": "1"},
files={"images": image}, timeout=60,
))
task_id = task["task_id"]
Path("hi3d-task-id.txt").write_text(task_id, encoding="utf-8")
print("Task ID:", task_id, flush=True)
# Query the saved task ID again if a client request times out.
deadline = time.monotonic() + POLL_WAIT_SECONDS
while time.monotonic() < deadline:
result = checked(requests.get(
BASE_URL + "/open-api/v1/query-task", headers=headers,
params={"task_id": task_id}, timeout=30,
))
state = result["state"]
print("State:", state, flush=True)
if state == "failed":
raise RuntimeError(result.get("msg") or "Task failed: " + task_id)
if state == "success":
with requests.get(result["url"], stream=True, timeout=60) as download:
download.raise_for_status()
with open("model.glb", "wb") as output:
for chunk in download.iter_content(chunk_size=65536):
output.write(chunk)
print("Saved model.glb")
break
if state not in ("created", "queueing", "processing"):
raise RuntimeError("Unexpected task state: " + str(state))
time.sleep(POLL_INTERVAL)
else:
raise TimeoutError("Client wait ended. Query the same task ID later: " + task_id)Common failures
If token exchange fails, check this site’s AK/SK. For creation failures, check parameters, files and credits. After a local request timeout, keep the original task ID and query it rather than automatically resubmitting. See Error handling.
API support:apicontact@hi3d.ai