公共打印文件 API

Base URL：https://app.customix.io/api

身份验证：如何获取 Customix API key

Authorization: Bearer {your-api-token}

速率限制：每分钟 100 次请求（按用户计）

概述

以纯文本的多行形式提交商品的定制内容，即可获得该次提交对应的
打印文件 URL 列表。

创建打印文件

POST /print-files

请求体

字段类型必填描述
shop_namestring是您的店铺名称（例如 my-etsy-shop）
namestring是您在此店铺中拥有的模板名称。将使用第一个与该名称匹配的模板。
contentstring是多行定制内容。每一行的格式为 <option name>: <value>。行首的 - 可有可无。

内容格式

每一行将模板上的一个可定制选项映射到一个值。

  • 选项名称的匹配不区分大小写，并忽略前后的空白字符。
  • 文本 / 颜色 / 日期选项按字面值取值，例如

Harry、#ffffff、2026-12-25。

  • 色板选项（字体、图片、颜色、版式等）接受一个整数，

用于选择可用的色板值之一。默认情况下，1 选择第一个
值，2 选择第二个，依此类推。

示例：

- Enter your name: Harry
- Text color: #ffffff
- Font: 1

响应 201

{
  "id": "01jyz5kqxz2hrcwqzdq4jdv7r9",
  "print_file_urls": [
    "https://.../1.png",
    "https://.../2.png"
  ]
}
字段类型描述
idstring该次提交的标识符
print_file_urlsstring[]模板上每个打印文件对应一个 URL，按模板中的顺序排列

生成完成后（通常在响应后几秒钟），即可通过返回的 URL 获取打印文件。

错误响应

状态响应体原因
401{"message": "Unauthenticated."}缺少 bearer 令牌或令牌无效
403{"message": "Unauthenticated"}令牌有效，但调用方无权访问 shop_name
404{"message": "Template not found: …"}此店铺中不存在具有该 name 的模板
422{"errors": {"shop_name": […], "name": […], "content": […]}}缺少必填字段
422{"message": "Unknown option: <name>"}某一行引用了模板上不存在的选项
422{"message": "Swatch index N is out of range for option '…' …"}色板索引超出可用范围
422{"message": "Option '…' expects an integer swatch index, got …"}向色板选项传入了非整数值

请求示例

curl -X POST 'https://app.customix.io/api/print-files' \
  -H 'Authorization: Bearer 01jyz0z…|abc…' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "shop_name": "my-etsy-shop",
    "name": "My Template",
    "content": "- Enter your name: Harry\n- Text color: #ffffff\n- Font: 1"
  }'

更新于：20/05/2026