#!/usr/bin/env python3 """Vertessia API client — one file, Python standard library only (3.9+). Library: from vertessia_client import Client c = Client(api_key="vk_live_...") c.accept_terms() # once per account (and again when the Terms change) job = c.convert("part.stl", target="step", surface="organic") done = c.wait(job) c.download(done, "./out") # a STEP download uses 1 credit / plan quota Command line (the key is read from VERTESSIA_API_KEY): python vertessia_client.py me python vertessia_client.py accept-terms --yes python vertessia_client.py convert ./*.stl --to step --surface organic --out ./out Every submission carries an Idempotency-Key derived from the file contents and the parameters, so re-running the same command after a crash or a timeout returns the same jobs instead of creating new ones (for 24 hours). 429 and 503 answers are retried after the server's Retry-After. Docs: https://vertessia.com/docs/api.html """ import argparse import glob import hashlib import json import os import sys import tempfile import time import urllib.error import urllib.parse import urllib.request import uuid from concurrent.futures import ThreadPoolExecutor, as_completed __version__ = "1.0.0" DEFAULT_BASE = "https://vertessia.com" SURFACES = {"organic": "nurbs", "mechanical": "smooth"} # 页面上的叫法 → API 的 surface 值 _CHUNK = 1 << 20 class ApiError(Exception): def __init__(self, status: int, detail: str, headers=None): super().__init__(f"HTTP {status}: {detail}") self.status, self.detail, self.headers = status, detail, headers or {} def file_sha256(path: str) -> str: h = hashlib.sha256() with open(path, "rb") as f: for chunk in iter(lambda: f.read(_CHUNK), b""): h.update(chunk) return h.hexdigest() def idempotency_key(path: str, params: dict) -> str: """同一个文件 + 同样的参数 → 同一个 key(服务端 24 小时内返回同一个任务)。""" raw = file_sha256(path) + json.dumps({k: v for k, v in params.items() if v not in (None, "")}, sort_keys=True) return "vtc-" + hashlib.sha256(raw.encode()).hexdigest()[:40] class _Body: """multipart 请求体:可重复迭代(重试时重新读文件),有长度(不用分块传输)。""" def __init__(self, head: bytes, path: str, tail: bytes): self.head, self.path, self.tail = head, path, tail def __len__(self): return len(self.head) + os.path.getsize(self.path) + len(self.tail) def __iter__(self): yield self.head with open(self.path, "rb") as f: for chunk in iter(lambda: f.read(_CHUNK), b""): yield chunk yield self.tail def multipart(fields: dict, file_field: str, path: str): boundary = "vtc" + uuid.uuid4().hex parts = [] for k, v in fields.items(): if v in (None, ""): continue parts.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{k}"\r\n\r\n{v}\r\n') name = os.path.basename(path).replace('"', "_") parts.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{file_field}"; filename="{name}"\r\n' f"Content-Type: application/octet-stream\r\n\r\n") return (f"multipart/form-data; boundary={boundary}", _Body("".join(parts).encode("utf-8"), path, f"\r\n--{boundary}--\r\n".encode())) class Client: def __init__(self, api_key: str = None, base_url: str = None, client_name: str = None, timeout: float = 300, max_retries: int = 8): self.api_key = api_key or os.environ.get("VERTESSIA_API_KEY", "") self.base_url = (base_url or os.environ.get("VERTESSIA_BASE_URL") or DEFAULT_BASE).rstrip("/") self.client_name = client_name or f"vertessia-python/{__version__}" self.timeout, self.max_retries = timeout, max_retries # ---------------------------------------------------------------- HTTP def _headers(self, extra=None) -> dict: h = {"User-Agent": f"vertessia-python/{__version__}", "X-Vertessia-Client": self.client_name, "Accept": "application/json"} if self.api_key: h["Authorization"] = f"Bearer {self.api_key}" h.update(extra or {}) return h def _request(self, method: str, path: str, *, json_body=None, body=None, headers=None, query=None): url = path if path.startswith("http") else self.base_url + path if query: url += ("&" if "?" in url else "?") + urllib.parse.urlencode({k: v for k, v in query.items() if v}) for attempt in range(self.max_retries + 1): h = self._headers(headers) data = None if json_body is not None: data = json.dumps(json_body).encode() h["Content-Type"] = "application/json" elif body is not None: data = body h["Content-Length"] = str(len(body)) req = urllib.request.Request(url, data=data, method=method, headers=h) try: with urllib.request.urlopen(req, timeout=self.timeout) as r: raw = r.read() return json.loads(raw) if raw else {} except urllib.error.HTTPError as e: detail = _detail(e) retry = e.code in (429, 503) or (e.code == 409 and "still being processed" in detail) if not retry or attempt == self.max_retries: raise ApiError(e.code, detail, dict(e.headers)) from None _sleep(e.headers.get("Retry-After"), attempt) except (urllib.error.URLError, TimeoutError, ConnectionError) as e: if attempt == self.max_retries: raise ApiError(0, f"network error: {e}") from None _sleep(None, attempt) # ---------------------------------------------------------------- API def config(self) -> dict: return self._request("GET", "/v1/config") def me(self) -> dict: return self._request("GET", "/v1/me") def accept_terms(self, version: str = None) -> dict: """接受现行条款 + 产物免责声明(https://vertessia.com/legal/terms.html)。条款版本变了要再接受一次。""" return self._request("POST", "/v1/me/accept-terms", json_body={"version": version or self.config()["terms_version"]}) def convert(self, path: str, target: str = "step", surface: str = None, patch_size: float = None, unit: str = None, callback_url: str = None, accept_terms: str = None, idempotency: str = "auto", **extra) -> dict: """提交一个文件,返回 {job_id, access_token, status, waiting, ...}。surface 可写 organic / mechanical。""" fields = {"target": target, "surface": SURFACES.get(surface or "", surface), "patch_size": patch_size, "unit": unit, "callback_url": callback_url, "accept_terms": accept_terms, **extra} headers = {} if idempotency == "auto": headers["Idempotency-Key"] = idempotency_key(path, {k: v for k, v in fields.items() if k != "accept_terms"}) elif idempotency: headers["Idempotency-Key"] = idempotency ctype, body = multipart(fields, "file", path) headers["Content-Type"] = ctype return self._request("POST", "/v1/convert", body=body, headers=headers) def status(self, job, access_token: str = "") -> dict: job_id, token = _job_ref(job, access_token) return self._request("GET", f"/v1/jobs/{job_id}", query={"k": token}) def wait(self, job, timeout: float = 3600, interval: float = 2, on_progress=None) -> dict: """轮询到 done / error(不抛异常:失败的任务看返回值的 status / error_class / message)。""" deadline = time.time() + timeout while True: st = self.status(job) if on_progress: on_progress(st) if st.get("status") in ("done", "error"): if isinstance(job, dict): st.setdefault("access_token", job.get("access_token", "")) return st if time.time() > deadline: raise TimeoutError(f"job {st.get('id')} still {st.get('status')} after {timeout:.0f} s") time.sleep(interval) interval = min(interval * 1.3, 10) def download(self, job, out_dir: str = ".", access_token: str = "", filename: str = None) -> str: """下载产物到 out_dir(没有就建;文件名用服务端给的,或 filename 指定)。走 download-link: 付费 STEP 在这里结算,同一个任务重复下载不重复扣。返回文件路径。""" job_id, token = _job_ref(job, access_token) link = self._request("POST", f"/v1/jobs/{job_id}/download-link", query={"k": token}) name = os.path.basename(filename or link.get("filename") or f"{job_id}.out") os.makedirs(out_dir, exist_ok=True) path = os.path.join(out_dir, name) # 链接本身带一次性令牌:不带 Authorization(带了服务端会改按登录身份校验,用任务令牌访问的匿名任务会 403) h = {k: v for k, v in self._headers().items() if k != "Authorization"} req = urllib.request.Request(self.base_url + link["url"], headers=h) fd, tmp = tempfile.mkstemp(prefix=name + ".", suffix=".part", dir=out_dir) # 并行下载各用各的临时文件 try: with os.fdopen(fd, "wb") as f, urllib.request.urlopen(req, timeout=self.timeout) as r: for chunk in iter(lambda: r.read(_CHUNK), b""): f.write(chunk) os.replace(tmp, path) except urllib.error.HTTPError as e: raise ApiError(e.code, _detail(e)) from None except (urllib.error.URLError, TimeoutError, ConnectionError, OSError) as e: raise ApiError(0, f"download failed: {e}") from None finally: if os.path.exists(tmp): os.remove(tmp) return path def convert_and_download(self, path: str, out_dir: str = ".", **kw): """提交 → 等 → 成功就下载。返回 (最终状态, 文件路径或 None)。""" job = self.convert(path, **kw) st = self.wait(job) if st.get("status") != "done": return st, None return st, self.download(job, out_dir) def _job_ref(job, access_token=""): if isinstance(job, dict): return job.get("job_id") or job.get("id"), access_token or job.get("access_token", "") return job, access_token def _detail(e: urllib.error.HTTPError) -> str: try: d = json.loads(e.read() or b"{}").get("detail") return d if isinstance(d, str) else json.dumps(d) except Exception: return e.reason or "" def _sleep(retry_after, attempt: int): try: wait = float(retry_after) except (TypeError, ValueError): wait = min(2 ** attempt, 60) time.sleep(min(max(wait, 0.5), 3600)) # ---------------------------------------------------------------- 命令行 def _cmd_convert(c: Client, a) -> int: files = [] for pat in a.files: # Windows 的 shell 不展开通配符:这里自己展开 hits = sorted(glob.glob(pat)) files += hits if hits else [pat] files = [f for f in dict.fromkeys(files) if os.path.isfile(f)] if not files: print("no input files", file=sys.stderr) return 2 os.makedirs(a.out, exist_ok=True) kw = {"target": a.to, "surface": a.surface, "patch_size": a.patch_size, "unit": a.unit, "callback_url": a.callback_url} # 输出文件名:同名输入(不同文件夹 / 不同格式)加 _2、_3,不互相覆盖 out_names, seen = {}, {} for f in files: stem = os.path.splitext(os.path.basename(f))[0] seen[stem.lower()] = seen.get(stem.lower(), 0) + 1 n = seen[stem.lower()] out_names[f] = f"{stem}{'' if n == 1 else f'_{n}'}.{a.to.lower()}" def one(path): try: job = c.convert(path, **kw) tag = " (reused)" if job.get("reused") or job.get("idempotent_replay") else "" print(f"[queued] {path} -> {job['job_id']}{tag}", flush=True) st = c.wait(job, timeout=a.timeout) # 超出套餐并发的任务会在服务端排队,等得久是正常的 if st.get("status") != "done": return path, False, f"{st.get('error_class') or 'error'}: {st.get('message')}" return path, True, c.download(job, a.out, filename=out_names[path]) except ApiError as e: if e.status == 400 and "accept-terms" in e.detail: return path, False, "accept the Terms first: python vertessia_client.py accept-terms --yes" if e.status == 402: return path, False, "not enough credits to download this result" return path, False, str(e) except Exception as e: # 等待超时等:记为这个文件失败,别让整批中断 return path, False, f"{type(e).__name__}: {e}" failed = 0 with ThreadPoolExecutor(max_workers=max(1, a.parallel)) as pool: for fut in as_completed([pool.submit(one, f) for f in files]): path, ok, info = fut.result() failed += not ok print(f"[{'done' if ok else 'failed'}] {path} -> {info}", flush=True) print(f"{len(files) - failed} of {len(files)} converted") return 1 if failed else 0 def main(argv=None) -> int: p = argparse.ArgumentParser(description="Vertessia API client") p.add_argument("--base-url", default=None, help=f"default {DEFAULT_BASE} (or VERTESSIA_BASE_URL)") sub = p.add_subparsers(dest="cmd", required=True) sub.add_parser("me", help="show account, credits and API limits") t = sub.add_parser("accept-terms", help="accept the current Terms of Service for this account") t.add_argument("--yes", action="store_true", help="I have read https://vertessia.com/legal/terms.html") cv = sub.add_parser("convert", help="convert files (globs allowed)") cv.add_argument("files", nargs="+") cv.add_argument("--to", default="step", help="target format: step, stl, obj, ply, 3mf, glb, ...") cv.add_argument("--surface", choices=sorted(SURFACES), default=None, help="mesh → STEP: organic (NURBS) or mechanical") cv.add_argument("--patch-size", type=float, default=None, help="organic patch size in mm") cv.add_argument("--unit", choices=["mm", "m", "in"], default=None, help="unit of the input file") cv.add_argument("--callback-url", default=None, help="https URL to POST to when each job finishes") cv.add_argument("--out", default=".", help="output folder") cv.add_argument("--parallel", type=int, default=4, help="files handled at the same time on this side") cv.add_argument("--timeout", type=float, default=24 * 3600, help="seconds to wait for each job (default 24 h)") a = p.parse_args(argv) c = Client(base_url=a.base_url) if not c.api_key: print("set VERTESSIA_API_KEY (create a key at https://vertessia.com/account.html)", file=sys.stderr) return 2 try: if a.cmd == "me": print(json.dumps(c.me(), indent=2)) return 0 if a.cmd == "accept-terms": v = c.config()["terms_version"] if not a.yes: print(f"Read https://vertessia.com/legal/terms.html (version {v}), then run again with --yes") return 2 print(json.dumps(c.accept_terms(v), indent=2)) return 0 return _cmd_convert(c, a) except ApiError as e: print(e, file=sys.stderr) return 1 if __name__ == "__main__": sys.exit(main())