欢迎来到 Quote3D 文档！⏳
Quote3D LogoQuote3D文档

核心概念：文件、报价与任务

本页面介绍驱动该平台的基础理念和模式。理解这些概念将帮助您充分利用 API，并为 3D 打印工作流程构建强大的集成。

API 基础路由

对于外部 API 调用，请直接向 https://api.quote3d.com/v2/... 发送请求（例如：GET https://api.quote3d.com/v2/user）。

在您的软件中，将 https://api.quote3d.com 设置为 API 主机/基础 URL，并调用诸如 /v2/user、/v2/file 和 /v2/quotes 等 v2 路径。

1. 身份验证与安全

每个端点都需要使用您的 Quote3D API 令牌进行身份验证，只有一个例外：文件管理中记录的公开上传路由。外部调用请使用 https://api.quote3d.com/v2 作为基础路由。令牌可以作为 Authorization: Bearer YOUR_TOKEN 或 X-API-Token 发送。请在 Quote3D 控制台生成令牌并妥善保密。

令牌可以设置作用域。完全访问令牌可到达所有端点，而小组件作用域的令牌仅限于嵌入式小组件所需的端点。调用作用域之外的任何内容都会返回 403。您可以在控制台的「令牌」页面查看和修改令牌的作用域。

提醒：请妥善保管您的 API token。切勿公开分享或提交到版本控制。

2. 账户管理

通过专用端点管理您的账户、上传文件和使用统计信息：

  • GET /v2/user 获取您的账户信息、套餐和每月额度——quotes_used、quotes_limit、storage_used、storage_limit 和 reset_date 都在这里
  • GET /v2/user/uploads 列出您上传到您账户的所有文件。这些文件按最新到最旧的顺序排列。
  • GET /v2/quota 获取您的速率限制额度——全局上限以及按端点细分的剩余调用次数和重置时间——同时返回今日、本月、本年及历史累计的请求数
  • GET /v2/usage 获取详细的使用分析，包括端点统计信息、材料使用情况和基于时间的趋势
  • GET /v2/config 账户已启用的技术、打印机、带颜色（有货或缺货）的材料以及定价默认值，也就是小组件提供的全部内容。小组件令牌也可以读取。

3. 文件管理

上传、下载和管理您的 3D 模型文件（STL、3MF、OBJ、STEP 格式）：

  • GET /v2/file/upload-id — 获取一个临时 upload_id，以便使用公共上传路由上传新文件。
  • POST /v2/file/public/{upload_id} — 此路由不需要身份验证。在您的客户端使用此路由可直接将文件上传到我们的存储空间。

    使用公共上传路由可避免将大文件通过您的后端服务器路由。这可以防止暴露您的 API 令牌并减少服务器负载。

  • POST /v2/file — 从您的服务器端上传文件（需要身份验证，当您想从后端上传时使用此方法）
  • GET /v2/file/{file_id} — 使用其 file_id 下载文件
  • DELETE /v2/file/{file_id} — 删除您不再需要的文件

如果文件不是有效的 STL、3MF、OBJ 或 STEP 模型，或超过平台文件大小上限（默认 50 MB），上传将被拒绝。STEP 文件（.step/.stp）会在服务器上使用与 OrcaSlicer 相同的设置进行网格化（线性偏差 0.003 mm，角度偏差 0.5 rad），装配体中的所有实体会被合并，长度换算为毫米。两个上传路由都会执行相同的检查。

文件存储方式

上传的模型以加密方式存储，且无法被公开访问——不存在可以直接提供已存储文件的链接。响应中的 file_path 字段是经过身份验证的下载路径（GET /v2/file/{file_id}），而非磁盘上的位置，因此请将其视为端点而非可分享的 URL。删除文件不仅会将其从您的列表中移除，还会将其从存储中彻底删除。

4. 部件信息与技术分析

检查模型是否可打印，并获取部件尺寸及高级技术指标：

  • POST /v2/printability/{file_id} 即时分析 – 在生成报价前，验证尺寸、体积、表面积和几何完整性（开口边缘/非流形）。

Quote3D 不仅仅进行简单的尺寸检查；它分析模型的流形（manifold）完整性并评估对 3D 打印至关重要的附着风险。这些指标在 Printability 和 Quote 响应中均有提供。

5. 报价操作

为您的 3D 打印生成即时报价并管理报价历史：

  • POST /v2/file/quote/{file_id} — 为 3D 模型启动异步报价计算。返回一个作业 ID；使用作业端点检索完成的结果。
  • POST /v2/file/quote/{file_id}/async — 替代的异步报价端点。返回一个作业 ID，您可以使用它来检查状态并获取完成的结果。
  • GET /v2/jobs/{job_id} — 检查异步报价作业的状态。返回进度百分比和完成状态。
  • GET /v2/quotes — 检索您的所有报价历史，支持分页
  • GET /v2/quotes/{quote_id} — 获取特定报价的详细信息
  • DELETE /v2/quotes/{quote_id} — 从您的历史记录中删除报价

异步工作流： POST /v2/file/quote/{file_id} 首先返回一个作业 ID。使用 GET /v2/jobs/{job_id} 获取简洁的完成结果，并使用 GET /v2/quotes/{quote_id} 获取可用的存储的详细报价数据。

报价请求参数

在生成报价时，您可以在请求体中提供自定义配置。您未指定的任何参数将自动从您的仪表板切片配置文件设置中获取。这允许您为每个报价覆盖特定设置，同时为其他设置保留默认值。

重要提示：如果您在请求中未提供参数，API 将使用您的仪表板切片配置文件（打印机配置文件、材料配置文件或全局设置）中的值。请确保在仪表板中设置您的默认配置文件，以获得一致的报价。您还可以配置仪表板上的特定打印机配置文件中的所有参数，并简单地在您的请求中传递其 'printer_id' 以立即应用这些设置，而无需单独传递它们。

配置优先级： V2 API 请求中发送的值会覆盖所选用户配置文件的值；任何仍然缺失的字段将回退到用户/全局默认配置文件。

下表涵盖了集成方最常覆盖的参数，但并非完整清单——报价引擎还接受更多打印机、材料和定价字段，而且每一项都可以在控制台的切片配置文件中设置一次，无需在每次请求时发送。请在那里配置好配置文件，只发送每次报价中变化的部分；完整字段清单见 OpenAPI 架构。

Request Validation

printer_config、material_config 和 quote_config 中的数值字段会在作业排队前进行边界校验。超出取值范围的值、非有限数值（NaN、Infinity）、错误的类型，或在只允许零及以上的位置出现的负数，都会以 HTTP 400 和指明具体字段的 VALIDATION_ERROR 被拒绝。在有意义的位置仍然接受零：按角色设置的速度或加速度为 0 表示“使用打印机默认值”，与 OrcaSlicer 采用的约定相同。

  • 温度限制：材料温度（temperature 和 bed_temperature，无论是在请求中发送还是从材料配置文件中读取）会与打印机的 min_hotend_temp / max_hotend_temp 以及 min_bed_temp / max_bed_temp 进行比对。若某种材料所需的温度超出所选打印机的能力，该请求将被拒绝而不会给出报价。仅适用于 FDM：树脂和粉末类技术既没有喷嘴也没有热床。将打印机的温度限制留空即可跳过此检查。
  • 已启用的技术类型：如果您在全局设置中限制了技术类型，针对已禁用技术的报价请求将被拒绝。将该设置留空即表示接受全部技术类型。
  • 材料价格字段：price_per_gram 是计价引擎实际使用的值。保存材料配置文件时，price_per_kg 会据此自动重新计算（若只提供每千克价格，则由 price_per_kg 推导出 price_per_gram），因此两者绝不会互相矛盾。

根参数

参数类型描述
technologystring可选。生产技术：'FDM'、'SLA'、'SLS'、'SLM' 或 'MJF'（'RESIN' 可作为 'SLA' 的别名，'DMLS' 和 'LPBF' 可作为 'SLM' 的别名）。它决定应用哪些技术专属参数，以及批量生产时零件如何排布。省略时使用所选打印机的技术，若仍无则回退为 'FDM'。
printer_idstring可选。要使用的特定打印机的 ID，而不是默认打印机。
quantitynumber可选。要生产的副本总数（默认：1）。

数量和批量生产逻辑

我们的系统利用基于指定 'quantity' 的高级打包算法：

  • FDM 技术：零件尽可能地并排放置在构建板上（X 轴和 Y 轴）。
  • SLA 技术：零件并排放置在树脂槽中（X 轴和 Y 轴）。
  • SLS 技术：零件可以堆叠在所有轴（X、Y 和 Z）上，以充分利用粉末床的容量。

由于这种优化的排布，如果多个零件可以放入一个批次，固定的额外成本（例如预热、冷却和层变化）仅应用于每个必需的批次。这确保了批量订单具有高度真实且具有成本效益的定价。

printer_config

打印机配置参数。所有字段都是可选的，如果未提供，将使用您的默认打印机配置文件值。

参数类型描述
nozzle_diameternumberFDM nozzle diameter (mm). Drives extrusion width, so it changes both print time and material use.
support_materialbooleanEnable support generation. When omitted, the profile value is used.
bed_size_xnumberBuild volume X dimension (mm)
bed_size_ynumberBuild volume Y dimension (mm)
bed_size_znumberBuild volume Z dimension (mm)
print_speednumberDefault print speed (mm/s)
max_print_speednumberMaximum print speed (mm/s)
travel_speednumberTravel speed (mm/s)
first_layer_speednumberFirst layer speed (mm/s)
layer_heightnumberLayer height (mm)
min_layer_heightnumberMinimum layer height (mm)
max_layer_heightnumberMaximum layer height (mm)
perimetersnumberNumber of perimeters/walls
top_solid_layersnumberTop solid layers count
bottom_solid_layersnumberBottom solid layers count
min_wall_countnumberMinimum wall count
max_wall_countnumberMaximum wall count
fill_densitynumberInfill density (0-100%)
infill_patternstring填充图案。默认值：rectilinear。基础类（rectilinear, alignedrectilinear, zigzag, crosszag, lockedzag, line, grid），三角形（triangles, trihexagon），立方体（cubic, adaptivecubic, supportcubic），蜂窝（honeycomb, honeycomb3d, lateralhoneycomb），高级（gyroid），特殊（monotonic, monotonicline），空间填充（hilbertcurve, archimedeanchords, octagramspiral）。hilbertcurve, archimedeanchords, octagramspiral 可被接受，但没有自己的生成器 —— 它们被视为 rectilinear。数值匹配不区分大小写且忽略分隔符，因此 tri-hexagon 和 Zig Zag 均有效；OrcaSlicer 的拼写方式 3dhoneycomb 同样被接受。lightning, quartercubic, laterallattice, crosshatch, concentric, tpmsd, tpmsfk 不受支持且将返回 400 错误。
support_overhang_anglenumberSupport overhang angle (degrees)
support_densitynumberSupport density (0-100%)
brim_enabledbooleanEnable brim generation for FDM quotes
brim_widthnumberBrim width in millimeters when brim is enabled
acceleration_printnumberPrint acceleration (mm/s²)
acceleration_travelnumberTravel acceleration (mm/s²)
acceleration_retractionnumberRetraction acceleration (mm/s²)
acceleration_outer_wallnumberOuter wall acceleration (mm/s²). 0 uses acceleration_print.
acceleration_inner_wallnumberInner wall acceleration (mm/s²). 0 uses acceleration_print.
acceleration_sparse_infillnumberSparse infill acceleration (mm/s²). 0 uses acceleration_print.
acceleration_solid_infillnumberSolid infill acceleration (mm/s²). 0 uses acceleration_print.
acceleration_top_surfacenumberTop surface acceleration (mm/s²). 0 uses acceleration_print.
acceleration_bridgenumberBridge acceleration (mm/s²). 0 uses acceleration_print.
acceleration_first_layernumberFirst layer acceleration (mm/s²). 0 uses acceleration_print.
retraction_minimum_travelnumberTravel moves shorter than this do not retract (mm). Reference default 1.
z_hop_mmnumberNozzle lift before a travel move (mm). 0 disables it. Reference default 0.4.
bed_exclude_xnumberUnusable bed edge margin on X (mm), removed from the packing area.
bed_exclude_ynumberUnusable bed edge margin on Y (mm), removed from the packing area.
jerk_printnumberPrint jerk (mm/s)
jerk_travelnumberTravel jerk (mm/s)
jerk_retractionnumberRetraction jerk (mm/s)
min_hotend_tempnumberMinimum hotend temperature (°C)
max_hotend_tempnumberMaximum hotend temperature (°C)
min_bed_tempnumberMinimum bed temperature (°C)
max_bed_tempnumberMaximum bed temperature (°C)
hourly_costnumberMachine hourly cost
SLA 专属
sla_exposure_timenumberSLA：每层曝光时间（秒）
sla_bottom_exposure_timenumberSLA：基准曝光时间（秒）
sla_bottom_layer_countnumberSLA：底层数量
sla_lift_distancenumberSLA：抬升距离（毫米）
sla_lift_speednumberSLA：抬升速度（毫米/秒）
sla_retract_speednumberSLA：回抽速度（毫米/秒）
sla_cleaning_costnumberSLA：每次打印的固定清洗成本（IPA、耗材）
sla_pad_enabledbooleanSLA：在底座/筏板上打印模型。默认关闭；底座树脂将与支撑材料一并计算。
sla_pad_wall_thicknessnumberSLA：底座壁厚（mm）。别名：sla_pad_height。
sla_pad_wall_heightnumberSLA：底座壁高（mm）（底座凹槽周围的凸起边缘）。
sla_pad_wall_slopenumberSLA：底座壁坡度（度，45-90）。底座以此角度向下收缩。
sla_pad_brim_sizenumberSLA：底座裙边尺寸（mm）。别名：sla_pad_expansion。
sla_pad_max_merge_distancenumberSLA：距离小于此值的支撑脚将合并为一个底座区域（mm）。
sla_support_head_front_diameternumberSLA：支持头前端（尖端）直径（mm）。
sla_support_head_penetrationnumberSLA：支持头嵌入模型表面的深度（mm）。
sla_support_head_widthnumberSLA：支持头杆长度（mm）。
sla_support_pillar_diameternumberSLA：支持柱直径（mm）。决定了大部分支撑树脂的体积。
sla_support_base_diameternumberSLA：支持柱底座（脚部）直径（mm）。
sla_support_base_heightnumberSLA：支持柱底座（脚部）高度（mm）。
sla_support_object_elevationnumberSLA：物体高于成型平台的高度（单位：mm）。这也会增加打印层数，从而影响打印时间。仅在生成支撑时应用。
sla_support_critical_anglenumberSLA：布置支撑时使用的桥接斜率（单位：度）。这与 support_overhang_angle 不同。
sla_support_max_pillar_link_distancenumberSLA：间距大于此值的支撑柱将不会进行交叉连接（单位：mm）。
sla_support_max_bridge_lengthnumberSLA：支撑头到达平台时可能采取的最长横向桥接长度（单位：mm）。
sla_support_max_bridges_on_pillarnumberSLA：单个支撑柱允许的桥接数量。
sla_support_points_densitynumberSLA：支撑点密度百分比，100 = 正常。这与 support_density 不同，后者是 FDM 支撑填充百分比。
sla_elephant_foot_compensationnumberSLA：底层向内缩进的距离，以抵消底部的扩宽。每台自带的 SLA 打印机参考值为 0.2。设置为 0 则禁用。
sla_elephant_foot_min_widthnumberSLA：比此值更窄的轮廓将保持不变，以免细微特征被抹除。参考值为 0.2。
sla_faded_layersnumberSLA：补偿量逐渐减弱至零所经过的层数。这并非底层层数；参考 MSLA 配置使用的是 8。
SLS 专用
sls_laser_speednumberSLS：激光速度（毫米/秒）
sls_hatch_spacingnumberSLS：扫描间距（毫米）
mjf_layer_timenumberMJF：每层秒数。HP 公布的构建速率恰好为：床面积 x 层厚 / 每层时间，因此该数值决定了整个构建时间；XY 几何形状不影响此项。4200 数据表指出，在 0.08 mm 层厚时为 7.55 秒。
mjf_layer_thicknessnumberMJF：层厚（mm）。HP 4200/5200 系列的出厂标准为 0.08 mm。
mjf_preheat_timeintegerMJF：构建开始前的预热时间（分钟）。由本次构建中的所有零件共享，并按比例计费。
mjf_cooling_timeintegerMJF：打印后的冷却时间（分钟）。粉末块在拆包前必须冷却；该时间由每个零件分摊并按比例计费。
mjf_powernumberMJF：机器平均功耗（W），用于计算能耗成本项。
mjf_bb_multipliernumberMJF：零件所收取的构建包络面（粉末块）分摊份额的倍数。0 = 不收取该零件在粉末块中所占据空间的粉末费用。
mjf_part_spacingnumberMJF：粉末块中零件之间的最小间距（mm）。这决定了单次打印可容纳的零件数量，从而影响每个零件分摊的预热、冷却和粉末费用。
slm_laser_speednumberSLM：激光扫描速度（mm/s）。供应商的构建速率定义为：层厚 x 扫描速度 x 填充距离 x 激光器数量，因此这四个字段共同决定扫描时间。
slm_hatch_spacingnumberSLM：相邻扫描线之间的距离（mm）。
slm_layer_thicknessnumberSLM：层厚（mm）。金属粉末床设备通常在 0.02-0.06 mm 之间。
slm_laser_countintegerSLM：激光器数量。作为整个扫描项的除数，与供应商的成型速率公式完全一致。它并不会缩短铺粉时间。
slm_contour_countintegerSLM：每层切片轮廓周围的轮廓（边界）扫描次数。0 = 无轮廓扫描。
slm_contour_speednumberSLM：轮廓扫描速度（mm/s）；通常比填充速度慢。
slm_jump_speednumberSLM：扫描矢量之间的激光器重新定位（跳转）速度（mm/s）。
slm_recoat_timenumberSLM：铺粉器每层所需的时间（秒）。供应商的成型速率数值不包括铺粉时间，因此与 SLS 不同，该值无法从公布的成型速率中推导而出——请在机器上进行实际测量。
slm_preheat_timeintegerSLM：成形室预热和惰性气体吹扫时间（分钟），由底板上的每个零件分摊。
slm_cooldown_timeintegerSLM：成形后的冷却时间（分钟），由底板上的每个零件分摊。
slm_powernumberSLM：机器平均功耗（W），用于计算能耗成本。
slm_part_spacingnumberSLM：构建底板上零件之间的最小间距（mm）。SLM 零件不能在 Z 轴方向堆叠——每个零件都焊接在底板上——因此这直接影响底板排版和每次成形的零件数量。
slm_build_plate_costnumberSLM：每次运行的构建底板成本，由该批次中的零件分摊。0 = 不计费。
slm_plate_removal_costnumberSLM：每次运行将零件从底板上分离（线切割或带锯）的成本，由该批次中的零件分摊。0 = 不计费。
slm_stress_relief_costnumberSLM：每次去应力退火炉循环的成本，由该批次中的零件分摊。0 = 不计费。
slm_inert_gas_flownumberSLM：打印过程中的氩气或氮气消耗量（升/分钟）。0 = 不计费。
slm_inert_gas_cost_per_liternumberSLM：每升惰性气体的价格，以报价货币计算。0 = 不计费。
slm_support_removal_cost_per_cm3numberSLM：每立方厘米支撑的手动去除成本。金属支撑具有承重和导热作用，需通过切割而非剥离来去除。0 = 不计费。
sls_layer_thicknessnumberSLS：层厚（毫米）
sls_layer_recoat_timenumberSLS：层铺粉时间（秒）
sls_preheat_timenumberSLS：预热时间（分钟）
sls_cooling_timenumberSLS：冷却时间（分钟）
sla_light_off_delaynumberSLA: Light-off delay for each layer (seconds).
sla_transition_layer_countnumberSLA: Number of transition layers.
sla_drain_holesarraySLA: Drainage holes configuration to prevent suction cups.
sls_bb_multipliernumberSLS：部件占用构建槽位每等效克数的机器空间附加费。槽位是指部件的最小体积包围盒加上其分摊的粉末间隙和不可用腔室边缘，因此即使模型旋转到达，该值也不会改变。0 表示禁用附加费。
sls_contour_countnumberSLS：激光在每个切片轮廓周围扫描的轮廓（边界）次数。0 表示禁用轮廓扫描。
sls_contour_speednumberSLS：轮廓扫描速度，单位为 mm/s。0 表示轮廓按 sls_laser_speed 速度扫描。
sls_jump_speednumberSLS：扫描矢量之间非烧结重新定位移动的振镜跳转速度，单位为 mm/s。0 表示跳转速度为 sls_laser_speed（上限）。
sls_part_spacingnumberSLS：部件周围的最小粉末间隙（单位：mm），同时应用于部件之间以及部件与腔室壁之间。它决定了单次构建可容纳的部件数量，因此影响机器空间占用份额和固定成本分摊。0 表示使用引擎默认值 3 mm。
max_volumetric_flownumberMaximum volumetric flow rate in mm³/s.

material_config

材料配置参数。所有字段都是可选的，如果未提供，将使用您的默认材料配置文件值。

材料配置文件集成：filament_type 参数应与您的仪表板材料配置文件中的材料名称匹配。当您指定 filament_type（例如 "PLA"、"ABS"、"PETG"）时，API 会自动从该材料配置文件加载所有属性，包括密度、温度、回抽设置和定价。

定价准确性：材料成本按 price_per_gram 计算。在材料配置文件中只需设置 price_per_kg 或 price_per_gram 其中之一即可——另一个会自动保持同步。您仍然可以在单次请求中通过 material_config 里的 price_per_gram 或 price_per_kg 覆盖价格。

示例：如果您在仪表板中有一个 "PLA" 材料配置文件，其中 price_per_kg: 20.0 且 price_per_gram: 0.02，您可以简单地在请求中发送 {"filament_type": "PLA"}，所有定价将自动计算。

参数类型描述
filament_typestringFilament type (PLA, ABS, PETG, etc.)
colorstring颜色名称（例如 'White'、'Black'、'#FFFFFF'）。注意：对于基于体积的技术（SLA、SLS、SLM、MJF），只有当 'post_processing' 设为 'painting' 或 'painted' 时才会应用颜色。
densitynumberMaterial density (g/cm³)
diameternumberFilament diameter (mm)
filament_flow_rationumberFDM 流量倍率。1.0 表示 100% 流量。请求值将覆盖所选的用户材料配置文件；如果缺失，则在默认值 1.0 之前使用全局配置文件值。
powder_bulk_densitynumberSLS: Bulk density of loose powder in g/cm³. Used for reusable powder and refresh calculations.
temperaturenumberPrint temperature (°C)
print_temp_minnumberMinimum print temperature (°C)
print_temp_maxnumberMaximum print temperature (°C)
bed_temperaturenumberBed temperature (°C)
bed_temp_minnumberMinimum bed temperature (°C)
bed_temp_maxnumberMaximum bed temperature (°C)
fan_speednumberFan speed (0-100%)
min_fan_speednumberMinimum fan speed (0-100%)
retraction_distancenumberRetraction distance (mm)
retraction_speednumberRetraction speed (mm/s)
slow_down_min_speednumberLower speed bound for layer cooling (mm/s). Reference default 20.
retraction_minimum_travelnumberOverrides the printer value for this material (mm).
z_hop_mmnumberOverrides the printer value for this material (mm).
price_per_kgnumberPrice per kilogram
price_per_gramnumberPrice per gram
support_cost_multipliernumberSupport material cost multiplier
sls_refresh_factornumberSLS powder refresh rate ratio (e.g. 0.3 = 30% fresh powder).
mjf_refresh_factornumberMJF 粉末刷新率（例如 0.2 = 20% 新粉）。HP 为每种粉末发布单独的比例，其测量方式与相同聚合物的 SLS 比例不同。若省略，则回退至 sls_refresh_factor。
mjf_fusing_agent_ml_per_cm3numberMJF：每立方厘米融合零件体积所消耗的融合剂（mL/cm3）。工厂测量值；0 表示将融合剂成本排除在报价之外。
mjf_detail_agent_ml_per_cm2numberMJF：每平方厘米熔合边界区域消耗的细节剂（mL/cm2）。工厂测量值；0 表示不计入。
mjf_agent_cost_per_liternumberMJF：报价货币中每升试剂的价格。0 将禁用试剂成本行。
metal_powder_loss_factornumberSLM：筛分和处理损耗，以零件及支撑体积的比例表示（0.05 = 5%）。未使用的金属粉末会经过筛分并重复使用，因此——与 SLS 和 MJF 不同——周围的粉末不计费。
max_volumetric_flownumberMaterial specific volumetric flow limit in mm³/s.
min_layer_timenumberMinimum layer time in seconds for cooling.

quote_config

报价定价配置参数。所有字段都是可选的，如果未提供，将使用您的默认全局设置值。货币默认为您的仪表板偏好设置（例如 "USD", "TRY", "EUR"）。

参数类型描述
currencystringCurrency code, one of TRY, USD, EUR, GBP, JPY, CNY, RUB, CAD, AUD, CHF, SEK, NOK, DKK, SGD, HKD, NZD, MXN, BRL, INR; case does not matter. Defaults to your dashboard preference.
tax_ratenumberTax rate percentage (0-100)
fixed_feenumberFixed fee per quote
minimum_pricenumber最低报价：整份报价的税前下限。更便宜的报价会提高到此金额，更贵的报价保持不变。默认使用您为该报价技术设置的最低价；0 = 无。
energy_cost_per_kwhnumberEnergy cost per kWh
hollowingstringSLA、SLS 和 MJF 专用：'solid'、'2mm' 或 '3mm'。当设置中启用了 SLA 掏空时，SLA 默认使用 '2mm'；SLS 和 MJF 同理，各自使用自己的设置。FDM 会忽略该参数（空腔由 fill_density 决定），SLM 也会忽略（密闭空腔会困住无法排出的粉末）。SLS 和 MJF 零件在掏空时不会开排粉孔：未烧结的粉末留在内部，按粉床密度而非实体密度计费，且无法回收。
post_processingstring基于体积的技术（SLA、SLS、SLM、MJF）：'standard'、'sanding'、'painting' 或 'painted'（默认：'standard'）。该值会记录在报价中，并按全局设置中各技术的后处理费用计价。SLM 的费用整体更高，因为即使是 'standard' 也包含将零件从成形基板上切下并清理表面。
sla_post_processing_fee_standardnumberSLA standard post-processing fee per part. Overrides the settings value; post_processing selects which one applies.
sla_post_processing_fee_sandingnumberSLA sanding post-processing fee per part. Overrides the settings value; post_processing selects which one applies.
sla_post_processing_fee_paintingnumberSLA painting post-processing fee per part. Overrides the settings value; post_processing selects which one applies.
sla_post_processing_fee_paintednumberSLA painted post-processing fee per part. Overrides the settings value; post_processing selects which one applies.
sls_post_processing_fee_standardnumberSLS standard post-processing fee per part. Overrides the settings value; post_processing selects which one applies.
sls_post_processing_fee_sandingnumberSLS sanding post-processing fee per part. Overrides the settings value; post_processing selects which one applies.
sls_post_processing_fee_paintingnumberSLS painting post-processing fee per part. Overrides the settings value; post_processing selects which one applies.
sls_post_processing_fee_paintednumberSLS painted post-processing fee per part. Overrides the settings value; post_processing selects which one applies.
mjf_post_processing_fee_standardnumberMJF：当 post_processing 为 'standard' 时收取的费用。
mjf_post_processing_fee_sandingnumberMJF：当 post_processing 为 'sanding' 时收取的费用。
mjf_post_processing_fee_paintingnumberMJF：当 post_processing 为 'painting' 时收取的费用。
mjf_post_processing_fee_paintednumberMJF：当 post_processing 为 'painted' 时收取的费用。
slm_post_processing_fee_standardnumberSLM：当 post_processing 为 'standard' 时收取的费用。
slm_post_processing_fee_sandingnumberSLM：当 post_processing 为 'sanding' 时收取的费用。
slm_post_processing_fee_paintingnumberSLM：当 post_processing 为 'painting' 时收取的费用。
slm_post_processing_fee_paintednumberSLM：当 post_processing 为 'painted' 时收取的费用。
mjf_min_build_fillnumberMJF：订单需支付的构建最低分摊比例。0 = 构建与其他订单共享，1 = 订单支付整个构建的费用。
enable_batch_systembooleanEnable/disable batch calculation system (default: true)
sls_min_build_fillnumberSLS：最小构建填充率，取值为 0 到 1 之间的比例。订单将按至少占据单次构建运行的该比例进行计费 —— 0 表示与其他任务共享构建，1 表示计费整个构建。当 enable_batch_system 为 false 时，此项将被忽略。
material_wastage_factornumberFactor for calculating material wastage (e.g. 1.10 for 10% wastage).
volume_discount_tiersarrayQuantity discount tiers, e.g. [{"minVolume": 100, "discount": 5}]. Falls back to your Global Settings tiers.

提示：报价会自动保存到您的帐户。您可以随时通过报价历史记录端点访问它们。

6. 打印机和报价配置

配置打印机设置和定价以获得准确的报价。您可以在仪表盘的切片配置部分管理您的默认配置，当您在 API 请求中未指定参数时，系统将自动使用这些配置。

配置类型

  • 打印机档案 - 配置您的打印机设置（打印床尺寸、喷嘴直径、打印速度、层高、加速度、抖动、温度等），以匹配您的实际打印机。在仪表盘中将其设置为您的默认档案，除非您覆盖特定参数，否则它将用于所有报价请求。
  • 材料档案 - 为您使用的每种材料设置材料属性（灯丝类型、密度、直径、温度、风扇速度、回抽设置、定价）。当您在请求中指定 filament_type 时，API 将自动使用匹配的材料档案。
  • 全局设置 - 配置全局报价设置，如税率、固定费用、能源成本和默认货币。这些设置适用于所有报价，除非在请求中被覆盖。

最佳实践：在仪表盘切片档案部分设置您的默认档案。这样，您可以在不指定所有参数的情况下提出简单的报价请求，API 将自动使用您配置的默认值。在需要时，您仍然可以按请求覆盖任何参数。

档案合并方式

当您提出报价请求时，API 会使用以下优先级将您的请求参数与仪表盘档案合并：

  1. 请求参数 - 您在 API 请求中明确提供的数值具有最高优先级
  2. 用户档案 - 如果您设置了用户特定的默认档案，则接下来使用它
  3. 全局配置 - 如果不存在用户配置，系统将回退到全局默认值。

这意味着您可以仅覆盖您需要的参数（例如，仅 layer_height 或 fill_density），同时保留来自仪表盘档案的所有其他设置。

7. Webhooks

当您的账户中发生事件时，接收实时通知：

  • POST /v2/webhooks - 创建新的 Webhook 端点
  • GET /v2/webhooks - 列出您的所有 Webhooks
  • GET /v2/webhooks/{webhook_id} - 获取 Webhook 详情和交付统计信息
  • PUT /v2/webhooks/{webhook_id} - 更新 Webhook 设置
  • DELETE /v2/webhooks/{webhook_id} - 删除 Webhook
  • POST /v2/webhooks/{webhook_id}/deliveries/{delivery_id}/resend - 重新发送一次过去的投递，例如在修复端点之后

支持的事件： quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart, usage.alert. Webhooks 包含 HMAC-SHA256 签名以进行安全验证。

Webhook 参考：载荷结构、签名验证、重试与重新投递

8. 分析与报告

获取您 API 的使用情况和报价统计信息：

  • GET /v2/analytics/quotes - 获取全面的报价统计信息，包括总报价数、平均价格、材料使用趋势
  • GET /v2/analytics/popular - 查看您最受欢迎的材料和打印机配置
  • GET /v2/analytics/cost-trends - 分析一段时间内的成本趋势（每日、每周或每月分组）
  • GET /v2/analytics/export - 将您的报价和使用数据导出为 CSV 或 JSON

9. 目录与库存

使用服务器令牌管理账户自己的打印机、材料、颜色、各颜色库存、定价和技术。小组件读取同一目录，因此更改会立即反映到报价表单。小组件令牌会被拒绝，这些调用不计入每月请求配额：

  • GET /v2/store/catalog - 账户提供的全部内容，包括各技术的就绪情况和即将用完的颜色
  • GET /v2/store/catalog/schema - 控制台的打印机、材料和定价表单，带有限值、单位和所请求语言的帮助文本
  • POST /v2/store/catalog/adopt - 将全局打印机和材料连同所选的颜色、价格和初始库存复制到账户
  • POST /v2/store/catalog/materials - 创建材料，可选择以某个全局材料为起点
  • GET · PATCH · DELETE /v2/store/catalog/materials/{id} - 读取、修改或删除单个材料，包括其库存设置
  • PUT /v2/store/catalog/materials/{id}/colors - 替换材料的颜色列表；现有颜色的库存保持不变
  • GET · PATCH · DELETE /v2/store/catalog/printers/{id} - 读取、修改或删除单台打印机
  • GET · PATCH · DELETE /v2/store/catalog/pricing - 读取、修改或重置定价设置；更改币种会更改账户币种，但不换算金额
  • GET · PUT /v2/store/catalog/technologies - 套餐允许哪些技术以及哪些已启用
  • GET · POST /v2/store/stock/movements - 记录入库、盘点或损耗，并列出库存记录
  • POST /v2/store/stock/orders - 扣减、退回或检查已付款订单的材料，每个报价最多一次

PATCH 请求体包含 values 和 updated_at。values 使用与目录列表相同的 snake_case 字段名（表单中没有的名称会以 400 拒绝）；如果配置文件在您读取后已被更改，调用会返回 409，error_key 为 stale。

10. 速率限制与配额

Quote3D 使用速率限制以确保公平使用和系统稳定性：

  • 速率限制应用于每个 API 令牌，并且因端点而异
  • 速率限制信息包含在响应头中： X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Window
  • 当达到速率限制时，您将收到 429 Too Many Requests 响应，其中包含 Retry-After 头
  • 您的套餐规定报价额度（每个计费周期重置）和存储额度（从不重置，只有删除文件才会释放）
  • 限制值可按部署配置，因此请读取当前值而不要写死在代码中。上面的响应标头和该端点都会报告这些值： GET /v2/quota

最佳实践：处理速率限制错误时实施指数退避，以避免使 API 过载。

11. 响应与错误

成功的响应有两种形式。报价、任务、已存报价详情、Webhook、分析、用量、配额和配置调用会用 success: true 包装内容，结果放在 data 下。文件、上传 ID、用户、上传列表、报价列表、可打印性以及目录与库存调用直接在顶层返回字段。每个调用的准确结构见 API 参考。文件下载和 CSV 导出返回原始文件内容。

{
  "success": true,
  "data": { "...": "endpoint-specific payload" }
}

分页与排序

/v2/quotes 和 /v2/user/uploads 等列表端点使用 limit 和 offset 查询参数分页（默认 50 条，最多 100 条）。除结果外还会返回包含 total、limit、offset、has_more、page 和 total_pages 的 pagination 对象，因此请使用 has_more，而不要自行推算列表末尾。排序使用 field:direction 形式的可重复单一参数，例如 ?sort=created_at:desc&sort=total_price:asc；上传记录默认按最新优先排列。

错误响应

所有错误形式相同：一个指明参数或字段的 detail 列表（loc、msg、code）、一个 error_code（如 AUTH_001）、一个 error_summary，以及在需要时的 recovery_suggestions 和 documentation_url。请根据 HTTP 状态码和 error_code 进行分支处理，而不要依赖可能改写的文本。

状态含义
400请求体或查询参数无效——字段格式错误、文件格式不受支持，或模型无法放入所选打印机。
401API 令牌缺失、格式错误、已过期或已吊销。
403令牌有效，但不允许执行此调用：作用域限制、不在令牌列表中的来源或 IP 地址（AUTH_004），或套餐额度已用完（RATE_002，附带 X-Quota-* 响应头）。
404请求的文件、报价、任务或 Webhook 不存在，或不属于您的账户。
429超出速率限制。请读取 Retry-After 标头并在重试前退避等待。
500服务器端意外错误。可以退避后重试；若持续出现，请附上时间戳联系支持团队。

异步报价有所不同：任务入队会以 202 成功返回，而随后失败的计算会在任务端点上表现为带有错误消息的 failed 状态，而不是 HTTP 错误。请始终检查任务状态，而不只是启动时收到的状态码。

12. RESTful、带版本的 API

  • 所有端点都经过版本化（例如：/v2/）
  • 使用标准的 HTTP 方法： GET, POST, PUT, DELETE
  • 由 OpenAPI 3.0.3 架构描述，可导入您自己的工具中
  • 破坏性变更与新增内容记录在 API 更新日志