API - 概览

API - 资源与导入

浏览资源目录、下载清单和文件，以及导入设计。

端点概览

方法端点说明访问权限
GET/public-api/v1/assets列出所请求类型的素材目录条目。任何已验证身份的凭据
GET/public-api/v1/assets/:type/:assetId返回包含可下载文件用途的素材清单。任何已验证身份的凭据
GET/public-api/v1/assets/:type/:assetId/files/:role按用途下载素材文件。任何已验证身份的凭据
GET/public-api/v1/design-imports列出托管在 Alter 上的可导入设计。已验证身份的凭据，需要 Business 套餐
GET/public-api/v1/design-imports/:id返回设计导入数据载荷和文件描述信息。已验证身份的凭据，需要 Business 套餐
GET/public-api/v1/design-imports/:id/files/:fileId从设计导入描述信息下载文件。已验证身份的凭据，需要 Business 套餐

素材目录

素材目录提供产品源素材、背景、环境、图形库条目、设计模板和样机素材。列表端点返回精简的描述信息，详情端点包含文件清单。

类型说明
products基础产品素材、预览、3D 模型、材质和纹理描述信息。
backgroundsViewer 静态背景。
environments环境贴图和预览图像。
image_library图形库素材，包括店铺范围内的图形。
design_templates设计模板预览和图层文件引用。支持 product_id 筛选。
mockups样机生成器素材、背景和叠加贴图。支持 product_id 筛选。

请求示例（fetch）

const assets = await alterFetch('/assets?' + new URLSearchParams({
  type: 'products',
  limit: '20',
  offset: '0',
  search: 'mug'
}));

const details = await alterFetch('/assets/products/4');

const fileResponse = await fetch(
  'https://alterproduct.com/public-api/v1/assets/products/4/files/preview_medium',
  {
    headers: authHeaders
  }
);

const fileBlob = await fileResponse.blob();

响应示例

{
  "type": "products",
  "items": [
    {
      "assetType": "products",
      "assetId": "4",
      "title": "Mug 450ml",
      "slug": "product-4",
      "description": "Base product 4",
      "primaryRole": "preview_big",
      "fileCount": 8,
      "remoteVersion": "1.0",
      "thumbnail": {
        "role": "preview_small",
        "fileName": "product-4-preview-small.png",
        "mime": "image/png",
        "downloadPath": "/v1/assets/products/4/files/preview_small"
      },
      "metadata": {
        "productCategoryId": 2,
        "productModelCount": 1,
        "isDedicated": false
      }
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

设计导入

设计导入提供托管在 Alter 上的设计及其文件，供外部生产或迁移流程使用。API 会检查是否符合 Business 套餐条件。

参数必填详情
search否搜索设计标题或 ID。
offset否默认为 0。
limit否默认为 20，最大为 100。

请求示例（fetch）

const imports = await alterFetch('/design-imports?' + new URLSearchParams({
  limit: '20',
  offset: '0',
  search: 'mug'
}));

const details = await alterFetch('/design-imports/381');

const fileId = details.files[0].id;
const fileResponse = await fetch(
  `https://alterproduct.com/public-api/v1/design-imports/381/files/${fileId}`,
  {
    headers: authHeaders
  }
);

const fileBlob = await fileResponse.blob();

响应示例

{
  "eligible": true,
  "requiredPlan": "Business",
  "currentPlanName": "Business",
  "designs": [
    {
      "id": 381,
      "title": "Men's T-Shirt",
      "createdAt": "2026-01-03T23:55:05.000Z",
      "sourceStorefrontId": 12,
      "productId": 4,
      "productName": {
        "pl": "Koszulka",
        "en": "T-Shirt"
      },
      "storageMode": "alter",
      "runtimeStatus": {
        "designer": true,
        "viewer": true,
        "configurator": true,
        "customizer": true
      },
      "thumbnail": {
        "kind": "design-mockup",
        "fileId": "7df7...",
        "downloadPath": "/v1/design-imports/381/files/7df7..."
      }
    }
  ],
  "total": 1
}