LoomLoom 开发者指南
把「一批同类任务」交给 LoomLoom 跑成流水线：查模板 → 填工作簿 → 校验 → 预估费用 → 提交 → 取结果。本文按接入顺序走完整链路，每步给出可复制的调用与对应接口文档。
一、接入前准备
- 创建 API Key：登录胜算云控制台创建密钥，所有请求在 Header 中携带
Authorization: Bearer YOUR_API_KEY。 - 认清两个地址：BASE URL 为
https://loomloom.shengsuanyun.com，接口路径统一以/loom/v1开头。 - 自检连通性：调一次余额接口，能返回余额就说明账号与网关都正常。
curl -X GET "https://loomloom.shengsuanyun.com/loom/v1/users/me/balance" \
-H "Authorization: Bearer YOUR_API_KEY"| 字段 | 说明 |
|---|---|
availableBalance | 可用余额（整数，最小单位为千万分之一元） |
availableBalanceMoney | 可用余额的金额对象（人民币） |
currency | 币种，如 CNY |
isSufficient | 余额是否充足 |
平台金额统一以千万分之一元为最小单位，
10000000 = 1 元。*T 结尾的字段都是这个单位，*Money 结尾的是对应金额对象。接口文档：GET /loom/v1/users/me/balance
二、先选路线：三条接入方式
| 路线 | 适合谁 | 关键接口组 |
|---|---|---|
| 官方模板 | 平台已内置你要的场景（批量写作 / 出图 / 出视频 / PRD 审核），想直接开跑 | Official Templates |
| 私有模板 | 要按自己的方法论搭多步工作流，自用、不上架 | User Templates |
| 市场工作流 | 想付费调用别人上架的工作流，或把自己的工作流上架收钱 | Market Listings · Market Runs |
三条路线共用同一套骨架——校验 → 预估 → 提交 → 轮询 → 取产物，差别只在模板从哪来、怎么计价。
三、完整链路
1. 认识可用模型
模板的每个步骤最终都要落到具体模型上。先看平台当前可用的模型、以及每个模型支持的步骤类型与参数契约：Models · 可执行模型。
2. 拿到模板与字段定义
先列出可用模板（返回 templateId、名称、场景、输入要求、输出类型），再取某个模板的 schema——里面写明有哪些字段、哪些必填、枚举可选值，以及可直接参考的示例行：
curl -X GET "https://loomloom.shengsuanyun.com/loom/v1/officialTemplates" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://loomloom.shengsuanyun.com/loom/v1/officialTemplates/{officialTemplate}/schema" \
-H "Authorization: Bearer YOUR_API_KEY"接口文档：列出官方模板 · 获取模板 schema
3. 用工作簿填数据
下载模板工作簿（.xlsx，表头已按字段预填），在下面逐行填数据；也可以不走工作簿，直接构造 JSON 行数据。两种方式等价，二选一即可。
curl -X GET "https://loomloom.shengsuanyun.com/loom/v1/officialTemplates/{officialTemplate}/workbook" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o template.xlsx| 规则 | 说明 |
|---|---|
| 表头不要改 | 表头是字段 key，删改列会导致整表无法识别 |
| 必填不能空 | 以 schema 中 required: true 为准 |
| 枚举只能填指定值 | 以 schema 中的可选值为准 |
| 行数据的 key 用中文字段标签 | JSON 行数据的 values 用 schema 里的中文 label，不是英文 key |
| 图片 / 文件字段 | 填公网可访问 URL，或先上传拿到 inputAssetId 再引用 |
自定义资产：非标准素材（图片、音频、文本）可先调
inputAssets:upload 上传，拿到的 inputAssetId（形如 ia_abc123）直接填进行数据的文件字段——以 ia_ 开头的值会被识别为已上传资产，而不是普通文本。见 Input Assets · 输入资产。4. 提交前校验
先校验再提交，避免跑到一半才发现格式错误。失败时返回行级错误（rowErrors），带上行号与字段名。
curl -X POST "https://loomloom.shengsuanyun.com/loom/v1/officialTemplates/{officialTemplate}:validateRows" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rows": [{"values": {"文本提示词": "写一段产品介绍", "写作要求": "简洁，80-120 字"}}]}'rowIndex 是 1-based：第 1 行是表头，数据从第 2 行开始。报「第 3 行某字段为空」对应的是 Excel 的第 3 行。5. 预估费用
提交前先算钱，顺便拿到 pricingRevision；提交时回传它可锁定计价版本，避免中途调价产生歧义。
curl -X POST "https://loomloom.shengsuanyun.com/loom/v1/officialTemplates/{officialTemplate}:precheckRows" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rows": [{"values": {"文本提示词": "写一段产品介绍"}}]}'6. 提交运行
校验通过、费用确认后正式提交。带上 clientRequestId 做幂等键，网络重试不会重复下单。提交成功返回 runId——后续所有查询都靠它。
curl -X POST "https://loomloom.shengsuanyun.com/loom/v1/officialTemplates/{officialTemplate}:runRows" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"rows": [{"values": {"文本提示词": "写一段产品介绍", "写作要求": "简洁，80-120 字"}}],
"clientRequestId": "order-20260914-001"
}'7. 轮询与取产物
任务异步执行。轮询运行状态到 completed / failed，再取产物与结果行：
# 运行状态
curl -X GET "https://loomloom.shengsuanyun.com/loom/v1/users/me/runs/{run}" \
-H "Authorization: Bearer YOUR_API_KEY"
# 产物列表（含可直接下载的 accessUrl）
curl -X GET "https://loomloom.shengsuanyun.com/loom/v1/users/me/runs/{run}/artifacts" \
-H "Authorization: Bearer YOUR_API_KEY"接口文档：Runs · 任务运行（运行详情、结果行、结果工作簿、产物列表）
建议每 5–10 秒轮询一次，不要用高频前端轮询硬刷；
accessUrl 是短期签名链接，拿到后尽快下载或转存，过期需重新获取。四、关键概念
| 概念 | 说明 |
|---|---|
runId | 一次批量运行的 ID。提交后所有进度查询、结果行、产物下载都以它为入口 |
row / task | 一行数据 = 一个任务。计费、状态、结果都以行为单位 |
clientRequestId | 幂等键：同一个值重复提交只会创建一次运行 |
pricingRevision | 计价版本号。预估时返回，提交时回传以保持价格一致 |
ia_ 前缀 | 已上传资产的引用标识，可直接填进文件字段替代公网 URL |
accessUrl | 产物下载地址，短期签名、无需额外认证 |
五、错误处理与常见坑
| 现象 | 排查方向 |
|---|---|
401 | API Key 缺失 / 失效 / 复制不完整（注意 Bearer 后的空格） |
400 invalid_request | 字段名或取值不合法：行数据用了英文字段 key、枚举填了未支持的值、必填留空 |
| 校验通过但运行失败 | 多为上游模型侧问题（内容审核、参数越界）。逐行看 errorMessage，成功行不必重跑 |
| 产物链接失效 | accessUrl 为短期签名，过期后重新调产物接口 |
| 余额不足 | 用余额接口确认可用余额；提交前先跑一次预估费用 |
批量任务不必整批重来：已成功的行结果保留，只需针对失败行重新组织一次提交（换新的
clientRequestId）。