图生 3D 怎么接入后台?异步任务实测
用一次真实 TRELLIS 请求展示提交、轮询、恢复下载与 GLB 验收,附 HTTP 404 对照、可运行 Python 和实际渲染。

产品后台在 3D 任务跑到一半时重启,恢复后应该还能取到原来的结果。2026 年 11 月 14 日,我们发出一次 TRELLIS 请求,收到 HTTP 202 和一个任务 ID。后面四次查到运行中,第五次查到完成并拿到 GLB 地址。保存文件后,只用记录下来的任务 ID 恢复下载,得到的字节完全一样。下面用这条真实 HTTP 轨迹说明状态写在哪里、失败后重试什么、下载回来怎样验收。
先说结论
- 一次 POST 返回 202 和 pending。五次 GET 使用同一个 ID。在提交响应之后 30.07 秒,客户端首次观察到完成。精度受轮询间隔限制。
- 下载返回 HTTP 200,GLB 有 1,820,056 字节、17,500 个三角面和一张内嵌图片。在 Three.js 中可以渲染,验证器报告零错误、零警告。
- 用一个故意未知的 ID 查询,返回 HTTP 404 和
prediction not found。重新查询已保存的真实 ID,仍能得到 completed,并取回同一份 GLB。 - 先保存服务端返回的 ID。遇到临时查询错误,用原 ID 重试 GET。提交结果不明时,先查清原请求是否已受理,再决定是否新提交。
1. 先核对所选路线的请求与返回
SandBase 的 HTTP 接口用 POST /v1/run 执行能力,用 GET /v1/run/{id} 查询异步结果。模型参数和 model 位于 JSON 的同一层。此次 TRELLIS 请求带一张图片的 URL、种子 73 和纹理尺寸 1024。其他路线的字段与输出格式可以不同,接入前按所选路线核对。本文的响应字段来自 HTTP API。 SandBase Run API · TRELLIS 图生 3D

从客户端收到提交响应时开始计时。每行来自一条真实 HTTP 响应,服务端可能在两次查询之间完成。
| 操作 | HTTP | 观察到的状态 | 提交响应后秒数 | 输出项 |
|---|---|---|---|---|
| 提交 | 202 | pending | 0.00 | 0 |
| 第一次查询 | 200 | running | 6.01 | 0 |
| 第二次查询 | 200 | running | 12.05 | 0 |
| 第三次查询 | 200 | running | 18.05 | 0 |
| 第四次查询 | 200 | running | 24.08 | 0 |
| 第五次查询 | 200 | completed | 30.07 | 1 |
初始响应只有 id、model 和 status。完成后的响应多了 outputs 数组。本次唯一的输出项包含 content_type 和 url。HTTP 200 只表示查询成功,是否再查取决于正文的状态。这个 30.07 秒记录适合解释程序如何观察状态。吞吐量或模型耗时要单独测量。
2. 应用任务和服务端任务 ID 都要保存
产品端可以在提交前先创建应用任务,记录所属用户、模型路线、输入引用、当前状态,以及稍后返回的服务端 ID 和已验证的文件位置。展示状态与文件前确认当前用户能访问这份任务。密钥只保留在服务端,临时文件地址和授权头也不要写进共享日志。本文用本地 JSON 表示一个单 worker。实际部署可为每个任务保存一条数据库记录,用事务或租约控制执行者。
最难处理的是 submitting。如果请求超时,或者服务端接受后本地进程马上退出,生成有可能已开始,而应用还没拿到 ID。示例在发请求前用独占创建写标记。结果不明时保留标记,后续通过请求日志或服务端记录核对。应用任务 ID 可以防止本地重复操作。服务端是否支持请求幂等,要看对应接口的文档。
3. 运行示例 worker
准备独立 Python 环境和服务端 SandBase 密钥。示例使用 Python 3 和 Requests,测试使用了路线公开的示例图。实际输入需能被所选路线读取。
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install requests把下面的代码保存成 run_job.py。提交和轮询是两个动作,进程重启后能读同一份任务记录继续。脚本限制轮询次数,处理临时 GET 错误,检查下载字节和 GLB 头部后再保存。示例每个任务由一个 worker 处理,任务和输出路径由服务端管理。
import argparse
import hashlib
import json
import os
from pathlib import Path
import struct
import time
from urllib.parse import quote, urlparse
import requests
BASE = "https://api.sandbase.ai/v1/run"
WAITING = {"pending", "running"}
TERMINAL_FAILURE = {"failed", "timeout", "cancelled"}
MAX_BYTES = 50_000_000
def save(path, value):
temp = path.with_suffix(".tmp")
temp.write_text(json.dumps(value, indent=2) + "\n")
temp.replace(path)
def download(url, destination):
if urlparse(url).scheme != "https":
raise ValueError("Expected an HTTPS output URL")
with requests.get(url, timeout=(5, 30), stream=True) as response:
response.raise_for_status()
data = bytearray()
for chunk in response.iter_content(65536):
data.extend(chunk)
if len(data) > MAX_BYTES:
raise ValueError("Output exceeds the download cap")
if len(data) < 20 or data[:4] != b"glTF":
raise ValueError("Expected a GLB container")
version, declared_size = struct.unpack_from("<II", data, 4)
if version != 2 or declared_size != len(data):
raise ValueError("Unexpected GLB version or length")
temp = destination.with_suffix(".partial")
temp.write_bytes(data)
temp.replace(destination)
return {"bytes": len(data), "sha256": hashlib.sha256(data).hexdigest()}
def submit(args, headers):
if not args.image:
raise SystemExit("--image is required for submit")
try:
with args.job.open("x") as job:
json.dump({"state": "submitting"}, job)
except FileExistsError:
raise SystemExit("Job already exists. Use poll with its saved run ID.")
try:
response = requests.post(
BASE, headers=headers, timeout=(5, 20),
json={"model": "trellis/trellis", "image": args.image,
"seed": 73, "texture_size": 1024},
)
response.raise_for_status()
body = response.json()
run_id = body["id"]
if not isinstance(run_id, str) or not run_id:
raise ValueError("Invalid provider run ID")
except (requests.RequestException, ValueError, KeyError) as error:
raise SystemExit(f"Submission unresolved. Keep the marker and investigate: {error}")
save(args.job, {"state": body["status"], "run_id": run_id})
print("Recorded", run_id, body["status"])
def poll(args, headers):
job = json.loads(args.job.read_text())
if not job.get("run_id"):
raise SystemExit("No run ID saved. Investigate the submission marker.")
url = f'{BASE}/{quote(job["run_id"], safe="")}'
for _ in range(24):
try:
response = requests.get(url, headers=headers, timeout=(5, 15))
except (requests.Timeout, requests.ConnectionError):
time.sleep(5)
continue
if response.status_code == 429 or response.status_code >= 500:
time.sleep(5)
continue
if response.status_code == 404:
raise SystemExit("Run lookup returned 404. Check the saved ID and credential.")
response.raise_for_status()
body = response.json()
state = body["status"]
save(args.job, {**job, "state": state})
if state == "completed":
output = next((item for item in body.get("outputs", [])
if item.get("content_type") == "model/gltf-binary"
and item.get("url")), None)
if output is None:
raise SystemExit("Completed run has no GLB output")
receipt = download(output["url"], args.output)
save(args.job, {**job, "state": "downloaded", **receipt})
print(json.dumps(receipt))
return
if state in TERMINAL_FAILURE:
raise SystemExit(f"Run ended in {state}: {body.get('error', '')}")
if state not in WAITING:
raise SystemExit(f"Unknown run state: {state}")
time.sleep(5)
raise SystemExit("Polling window ended. Resume polling the saved run ID.")
def main():
parser = argparse.ArgumentParser()
parser.add_argument("action", choices=("submit", "poll"))
parser.add_argument("--job", type=Path, default=Path("job.json"))
parser.add_argument("--image")
parser.add_argument("--output", type=Path, default=Path("asset.glb"))
args = parser.parse_args()
headers = {"Authorization": "Bearer " + os.environ["SANDBASE_API_KEY"]}
if args.action == "submit":
submit(args, headers)
else:
poll(args, headers)
if __name__ == "__main__":
main()先提交一次。以下命令会发起真实生成并可能产生费用,所用字段和本次实测相同。
python3 run_job.py submit --job character-job.json \
--image https://static.sandbase.ai/examples/trellis/trellis/input_image_0.png异步提交成功后,记录里应有 ID 和 pending 或 running 状态。本次线上轨迹由单独的日志客户端捕获。示例 worker 的首次提交和防重分支用模拟响应验证,真实已保存的 ID 用于测试轮询和下载。
python3 run_job.py poll --job character-job.json --output asset.glb下载成功后,本地记录写入 downloaded、字节数和 SHA-256。服务端原始状态是 completed。先落盘完成状态,再尝试取文件。若取文件失败,可以回到同一个 ID 恢复查询。如果调度器已确认文件保存成功,可以直接跳过。实测为核对字节一致性重新取了一次文件。
4. 按失败发生的位置重试

前两张卡片来自线上 GET。右侧是本地重复提交检查的结果。
| 情况 | 示例做法 |
|---|---|
| 正文仍是 pending 或 running | 等一会,再查询同一 ID |
| GET 超时、连接失败、429 或 5xx | 在轮询上限内重试该 GET |
| GET 返回 404 | 停止,核查保存的 ID 和密钥 |
| 正文是 failed、timeout 或 cancelled | 保存服务端状态,结束本轮 worker |
| 已完成,文件下载失败 | 用同一 ID 恢复取件 |
| 提交结果不明 | 保留提交标记并核查 |
本地模拟了一次 429,后续状态为 failed。两次 GET 的 ID 一样,没有额外发 POST,failed 也写入了本地任务。真实未知 ID 的 404 则只返回短错误,没有任务状态和输出。两种失败的排查入口不同。生产系统需要等更久时,可把下次检查时间存入队列,按退避策略调度。示例为了便于运行,在同一进程中等待。
5. 下载后核对字节和画面

画面来自保存下来的 GLB。重新查询原 ID 后取回的文件,SHA-256 与图中一致。
下载使用响应给出的 URL,未把 API 授权头发给存储域名。返回媒体类型为 model/gltf-binary。文件以 glTF 开头,版本为 2,声明长度与收到的字节一致。实际有 17,500 个三角面和一张图片。Khronos 验证器给出零错误、零警告,Three.js 打开文件并渲染了三个角度。到这一步可确认文件可读取,是否满足具体业务的部件要求,还要继续检查画面。 GLB 自动验收实测
用下面命令查看文件和本地记录。1,820,056 字节是这一份下载的实测值,再生成一次可能得到不同大小。
wc -c asset.glb
python3 -m json.tool character-job.json如果要把产物落到自己的存储,确认上传的字节与本地文件一致后,再更新应用状态。把哈希和目标位置一起保存,临时地址只在取件时使用。若链接在取件前已失效,按所用路线的实际行为确认能否恢复。无法恢复时给任务记录明确的交付失败状态,避免前端把服务端的 completed 直接显示为下载可用。
让前端看到任务卡在哪一步
前端需要区分已受理、等待取件和文件已验证三种状态。保留最近一次有意义的错误和时间。查询暂时不可用时,继续展示上一次确认的状态,以及计划再次查询的时间。
一次要处理多条任务时,可以参考图生 3D 批处理的提交、重试和费用记录。
常见问题
30.07 秒是模型的精确生成时间吗?
这是客户端从收到 202 到某次查询发现 completed 的间隔。服务端完成可能发生在两次查询之间。衡量产品体验时,可以分别记录提交、观察到完成、下载和首个可用画面的时间。
这次用到 3D webhook 了吗?
本文用轮询。SandBase 文档说明符合条件的异步图片、视频和音频任务可用 webhook。给具体 3D 路线加回调前,应查明那条路线是否支持。 SandBase webhook 说明
worker 重启后从哪一步继续?
有服务端 ID 时,先查状态。已有验证过的文件时,可以从已保存的应用状态继续。如果只有提交标记,先调查原来的请求是否已受理,再决定是否需要提交新请求。
觉得有用?分享给更多人