Hi3D 图生 3D API 使用文档

标签： 异步任务 · PNG / JPEG / WEBP · 单图输入 · 最大 20 MB

01 · 快速开始

准备一张公网可访问的产品图片，或使用 Base64 / Data URL。

使用客户 API Key 调用 POST /v2/j2ya5/{model_id}/hi3d/v1/submit-task，保存返回的 task_id。

轮询 GET /v2/j2ya5/query/{model_id}/{task_id}，状态为 success 后下载模型文件。

重要： 提交接口是异步任务接口。网络超时后不要立即重复 POST，先使用已有任务 ID 查询，避免重复创建任务。

项目	说明
API 地址	本服务的正式公网 API 地址为：`https://vg-api.aig-ai.com/`
请求头	每次请求都携带：`Authorization: Bearer YOUR_API_KEY`

图片要求： 图片必须能从公网访问；支持 PNG、JPEG、WEBP；单张图片不超过 20 MB。目前每个任务只支持一张输入图片。

POST /v2/j2ya5/{model_id}/hi3d/v1/submit-task

推荐使用 model 选择质量档位。系统会自动将模型档位映射到上游参数，不需要自行填写内部分辨率。

请求参数

参数	必填	说明
`image_url`	三选一	公网图片地址
`image_base64`	三选一	纯 Base64 图片内容
`image_data_url`	三选一	`data:image/png;base64,...` 格式
`model`	是	`hi3d-sparc3d`（标准）或 `hi3d-sparc3d-master`（高质量）
`request_type`	否	`1` 仅几何；`2` 纹理阶段；`3` 完整流程，默认 `3`
`pbr`	否	`1` 开启 PBR；`0` 关闭
`rmbg`	否	是否移除背景，默认由服务配置
`shading`	否	着色参数，例如 `0.5`
`face`	否	目标网格面数
`format`	否	`1=obj`、`2=glb`、`3=stl`、`4=fbx`、`5=usdz`、`6=3mf`

如果不确定参数，建议只传 image_url、model 和 format，其余使用默认值。

请求示例：

成功响应示例：

{
  "code": 200,
  "data": {
    "task_id": "task_xxx"
  }
}

建议： 将 task_id 持久化到你自己的订单或任务记录中，后续使用它查询状态。

GET /v2/j2ya5/query/{model_id}/{task_id}

请求示例：

任务状态说明：

下载时效： 模型和封面 URL 通常约 1 小时有效。任务成功后请尽快下载并保存到自己的对象存储。建议轮询间隔 3–5 秒，并设置合理的总超时时间。