快速开始
Hi3D API 根据图片生成 3D 模型。生成是异步任务:提交后保存 task_id,查询成功后下载结果。
| 参数 | 值 |
|---|---|
| Base URL | https://api.hitem3d.ai |
| Authorization | Basic 换取 Token,Bearer 调用接口 |
| 协议 / 响应 | HTTPS / application/json |
准备条件
- 登录本站账户,领取试用或购买积分包。
- 创建并启用 API 密钥,取得 Access Key 和 Secret Key。Secret Key 仅在创建时显示一次。
- 将密钥分别保存为服务端环境变量
HI3D_ACCESS_KEY和HI3D_SECRET_KEY,避免在前端暴露密钥。
鉴权方式
- 使用 Access Key 和 Secret Key 进行
Basic鉴权,调用获取 Token接口,读取响应中的data.accessToken。 - 提交任务、查询任务或查询余额时,发送请求头
Authorization: Bearer <accessToken>。将<accessToken>替换为上一步返回的值。
这套 API 流程只在换取 Token 时使用 API 密钥。后续调用使用 Access Token,减少 Secret Key 在业务请求中的传递。
1. 获取 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())检查业务响应后,读取data.accessToken并保存为HI3D_TOKEN。HTTP成功不等于业务调用一定成功。
{
"code": 200,
"data": {
"accessToken": "<TOKEN>",
"tokenType": "Bearer",
"nonce": "<NONCE>"
}
}2. 提交任务
示例使用hi3dv3.0、2048quality、几何+纹理、PBR开启,输出GLB。将input.png替换为本地图片;此组合为 45 积分,具体计费见模型定价。
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"
}保存data.task_id为HI3D_TASK_ID。提交成功表示任务已受理,尚未生成完成。
3. 查询状态
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())始终用同一个 task_id 查询,并按 data.state 处理。
created、queueing或processing:等待后继续查询。success:读取data.url。failed:停止轮询并查看错误。
按业务需求和服务端限制设置轮询间隔。详见异步任务与结果。
{
"code": 200,
"data": {
"task_id": "<TASK_ID>",
"state": "success",
"id": "<RESULT_ID>",
"url": "<RESULT_URL>",
"cover_url": "<COVER_URL>"
},
"msg": "success"
}4. 下载结果
将成功响应data.url保存为HI3D_RESULT_URL。结果和封面链接有效期为 1 小时,请及时保存文件。
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)将尖括号占位符替换为实际响应值。示例不会在本页自动执行。
完整 Python 示例
安装依赖 pip install requests,设置 HI3D_ACCESS_KEY、HI3D_SECRET_KEY,并准备当前目录的 input.png。示例完成鉴权、提交、轮询与下载,并将任务 ID 保存到本地。
轮询间隔与等待上限是示例客户端设置,可按业务调整,不代表服务端限额或 SLA。客户端等待结束后继续查询原任务,避免再次运行提交步骤创建新任务。
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)常见失败
获取 Token 失败时先检查本站 AK/SK;提交失败时检查参数、文件和可用积分。本地请求超时后保留原任务 ID 并查询,不自动重复提交。详细说明见 错误处理。
技术支持:apicontact@hi3d.ai