CGTrader是海外知名的3D模型交易市场，聚集了大量高质量的模型资源，很多设计师和工作室都在上面出售自己的作品。如果只是偶尔上传几个模型，用网页后台操作就够了，但对于拥有成百上千个资产、需要持续更新价格和跟踪订单的团队来说，手动维护几乎是不可能的任务。CGTrader为此开放了API接口，允许开发者用程序化的方式管理商品、查询交易数据，把整个运营流程自动化。这篇文章就来聊聊这套API的定位、接入方式和实际使用中的注意事项。
CGTrader API能做什么：核心能力概览
CGTrader API整体上是一套REST风格的HTTP接口，数据格式以JSON为主。它的能力范围基本覆盖了3D资产运营的各个环节。首先是商品管理，你可以通过接口创建新的模型商品、更新标题描述、调整价格、管理预览图和标签，这对批量上架特别有用。一个模型工作室通常有规范化的命名体系和分类逻辑，用脚本批量创建商品比在网页上一个个填表单效率高出一个量级。
其次是订单与销售数据查询。接口可以按时间范围拉取订单列表，包括买家信息（脱敏后）、成交金额、佣金比例等字段，方便你导入自己的财务系统做对账。再配合收益统计接口，可以算出每个时间段、每个资产类目的实际收入，为选品和定价策略提供数据支撑。
最后是资产状态同步。模型是否有新版本、是否被平台审核退回、是否需要补充格式文件，这些状态变化都能通过接口获取。你可以写一个定时任务，每天自动检查一次，把异常状态的资产汇总推送到内部群，避免错过平台的审核反馈。
如何申请与配置API访问权限
CGTrader的API访问需要先注册开发者账号，然后在个人设置的开发者页面创建应用，获取API Key和Secret。需要注意的是，这套凭证分为测试环境和生产环境两套，测试环境的沙盒数据不会影响真实店铺，建议先在沙盒环境把流程跑通再切换。
拿到密钥之后，认证方式一般采用请求头携带令牌的模式。下面是一个用Python获取访问令牌并发起请求的示例：
import requests
# 使用申请到的密钥换取访问令牌
def get_token(client_id, client_secret):
url = "https://api.cgtrader.com/oauth/token"
payload = {
"grant_type": "client_credentials",
"client_id": client_id,
"client_secret": client_secret
}
resp = requests.post(url, data=payload, timeout=15)
resp.raise_for_status()
return resp.json()["access_token"]
# 携带令牌查询自己的商品列表
def list_products(token, page=1):
url = "https://api.cgtrader.com/v1/products"
headers = {"Authorization": "Bearer " + token}
params = {"page": page, "per_page": 50}
resp = requests.get(url, headers=headers, params=params, timeout=15)
resp.raise_for_status()
return resp.json()令牌有有效期，过期后需要重新获取。实践中建议把令牌缓存起来，并在收到401响应时自动刷新，而不是每次请求都重新申请，这样能显著减少不必要的认证开销。密钥一定要放在服务端的环境变量或配置中心里，千万不要硬编码进代码仓库，更不能暴露在前端页面中。
批量上传与更新3D资产的实践方案
批量操作是这套API最有价值的场景。假设你本地有一个资产目录，每个模型文件夹里包含模型文件、预览图和一份描述信息，就可以写脚本扫描目录并逐个调用创建接口。需要注意模型文件本身通常不直接走API上传，而是先上传到平台指定的存储位置，拿到文件引用后再附加到商品数据中。
import os, json, time
def batch_publish(token, asset_dir):
# 扫描本地资产目录，读取每个模型的元信息
tasks = []
for folder in os.listdir(asset_dir):
meta_path = os.path.join(asset_dir, folder, "meta.json")
if not os.path.exists(meta_path):
continue
with open(meta_path, "r", encoding="utf-8") as f:
meta = json.load(f)
tasks.append({"name": folder, "meta": meta})
results = []
for task in tasks:
try:
product = create_product(token, task["meta"])
results.append({"name": task["name"], "id": product["id"], "ok": True})
except Exception as e:
results.append({"name": task["name"], "error": str(e), "ok": False})
time.sleep(1) # 控制请求节奏，避免触发频率限制
return results更新已有资产时，建议采用增量策略：先拉取远端商品列表，和本地元数据做对比，只对发生变化的字段发起PATCH请求。这样既能节省接口配额，也能降低误操作风险。批量操作一定要记录日志，把每个请求的响应保存下来，一旦中途失败可以断点续传，而不是从头再来。
限流、错误处理与稳定性建议
和所有开放平台一样，CGTrader API有调用频率限制，超出限制会返回429状态码。合理的做法是在客户端实现限流器，控制每秒请求数在安全范围内，同时采用指数退避策略处理偶发的429和5xx错误。下面是一段带重试逻辑的请求封装：
import time, requests
def request_with_retry(url, headers, max_retries=5):
for attempt in range(max_retries):
resp = requests.get(url, headers=headers, timeout=15)
if resp.status_code == 200:
return resp.json()
if resp.status_code in (429, 500, 502, 503):
wait = 2 ** attempt # 指数退避：1秒、2秒、4秒...
time.sleep(wait)
continue
resp.raise_for_status()
raise RuntimeError("接口连续重试失败: " + url)除了限流，还要注意网络层面的稳定性。海外接口在国内访问可能不稳定，如果部署在国内服务器，建议加上超时控制和失败告警。数据层面要做好幂等设计，比如创建商品前先查询是否已存在同名资产，避免重试机制导致重复上架。
总的来说，CGTrader API为3D资产的规模化运营提供了扎实的基础，从商品管理到数据对账都能覆盖。接入时把认证、限流、幂等这几个关键点处理好，再配合定时任务和监控告警，就能搭建起一套省心的自动化工作流，把精力真正放回内容创作本身。
CGTrader API3D资产API对接修改时间：2026-09-08 05:14:27