SUZURI API 用于构建与 SUZURI（suzuri.jp）联动的应用，可实现原创周边的创建、搜索与展示。基础信息：API 基址 https://suzuri.jp/api/v1，必须使用 HTTPS，GET 用查询字符串，POST/PUT/DELETE 用 application/json，响应为 JSON；JSON Schema 见 GET https://suzuri.jp/api/v1/schema。最新规范以 https://suzuri.jp/developer/documentation/v1 为准，推荐入稿尺寸见 https://suzuri.jp/item_templates。
认证有两种方式。API 密钥适合绑定自己账号的应用，在 https://suzuri.jp/developer/apps 发行，请求头为 Authorization: Bearer {api_key}，scope 分 read 与 write；注意会返回发行者自身的非公开商品，只想处理公开商品时用 published 字段过滤。OAuth 2.0 适合多用户各自账号操作的应用：引导至 GET https://suzuri.jp/oauth/authorize（client_id、scope、redirect_uri、response_type=code），授权后回调返回 code，再 POST https://suzuri.jp/oauth/token（Content-Type: application/x-www-form-urlencoded）换取令牌。回调 URL 每个应用只能设置一个，redirect_uri 必须为 HTTPS，环境不同需分别注册应用。
资源结构：Item（商品种类）含 ItemVariant（颜色尺寸组合），Material（用户上传的素材）生成 Product（素材×Item 的组合），Choice（商品集合）可加入 Product，Favorite 为商品点赞。创建素材会自动为指定 Item 生成商品，删除素材会连带删除关联商品。
主要端点包括 GET /items、GET/POST /materials、POST /materials/text、PUT/DELETE /materials/{id}、GET /products、/products/{id}、/products/search、/products/on_sale、GET/POST/PUT/DELETE /choices、/products/{id}/favorites、GET /users、/users/{id}、/user、/activities、/activities/unreads。列表接口支持 limit（默认约 20–30，最大 50）与 offset，meta.hasNext 表示还有下一页。
创建素材示例：POST /api/v1/materials 发送 JSON，含 texture（图片 URL 或 data URI）、title、price（创作者分成，非负整数）、description、products（itemId 与 published；itemId 需先通过 GET /api/v1/items 获取），resizeMode 可选 contain 或 cover，部分刺绣类 Item 不支持 API 创建。文本素材用 POST /api/v1/materials/text，发送 text（255 字符以内）与 itemVariantId。展示时推荐使用 sampleImageUrl（WebP），链接用 sampleUrl；imageUrl 为模板 URL，可替换 {width}x{height}、{size}、{color}、[/angle]。
限流可通过响应头 X-Ratelimit-Limit、X-Ratelimit-Remaining、X-Ratelimit-Reset 查看，涉及 POST /materials、PUT /materials/{id}、POST /materials/text、POST /products/{id}/favorites。错误按 HTTP 状态码判断，不保证响应体内容。价格由素材分成、ItemVariant 价格与打印位置附加费构成，最终含税价见 priceWithTax。其他参数细节、收费与价格等资料未提供。