Loomloom开发者指南

一步步教你使用 Loomloom 批处理 API。从健康检查到提交任务、下载结果，跟着做就行。

准备工作

获取 API Key，确认服务可用。

获取 API Key

登录胜算云控制台，在「API Key 管理」中创建密钥。所有请求都需要在 Header 中携带：

HTTP HeaderAuthorization: Bearer YOUR_API_KEY

检查服务是否可用

调用健康检查接口，确认服务正常：

cURLcurl -X GET "https://loomloom.shengsuanyun.com/batch/v1/health" \ -H "Authorization: Bearer YOUR_API_KEY"

字段	说明
`healthy`	true 表示服务正常
`message`	状态描述信息

成功标志

返回 {"healthy": true} 就可以开始下一步了。

API 参考 · GET /v1/health

查看可用模板

Loomloom 内置了一批模板，每个模板对应一种批处理场景（如电商产品图、文案生成等）。

获取模板列表

cURLcurl -X GET "https://loomloom.shengsuanyun.com/batch/v1/templates" \ -H "Authorization: Bearer YOUR_API_KEY"

字段	说明
`templateId`	模板唯一标识，后续所有操作都需要它
`name`	模板名称
`scenario`	适用场景说明
`inputSummary`	输入要求概述（如"每行填写一段提示词"）
`outputType`	输出类型（如"图片"、"文本"）

小贴士

把返回的 templateId 记下来，后面每一步都要用到。

API 参考 · GET /v1/templates

深入了解模板

查看模板的详细字段定义，下载 Excel 模板。

获取模板表单 schema

了解这个模板有哪些字段、哪些必填、支持什么类型的输入：

cURLcurl -X GET "https://loomloom.shengsuanyun.com/batch/v1/templates/{templateId}/schema" \ -H "Authorization: Bearer YOUR_API_KEY"

字段	说明
`fields`	字段列表，每个字段有 key、label、required、type 等
`columns`	Excel 列定义（fieldKey 对应 fields 中的 key）
`instructions`	填写说明数组
`sampleRows`	示例行数据，可以参考格式

下载 Excel 模板

cURLcurl -X GET "https://loomloom.shengsuanyun.com/batch/v1/templates/{templateId}/download" \ -H "Authorization: Bearer YOUR_API_KEY" \ -o template.xlsx

注意

下载的是 .xlsx 文件，用 Excel 或 WPS 打开。表头已经预填好，你只需要在下面的行里填写数据。

API 参考 · GET /v1/templates/{templateId}/schema & /download

准备数据

打开下载的 Excel，按模板要求填写数据。

填写规则

表头行不能改 — 表头是字段 key，系统靠它识别列
必填字段不能为空 — 参考 schema 中的 required: true
枚举字段只能填指定值 — 参考 schema 中的 enumValues
图片/文件字段 — 可以填公开 URL 或 inputAssetId（先通过上传接口获取）

小贴士

如果模板有 sampleRows，参考示例行的格式填写。

自定义工作流特色

Loomloom 的核心特色：上传任意资产（文本、图片等），直接触发自定义工作流。

两条路径，一个平台

Loomloom 提供两种使用方式：

官方模板路径（步骤 2-4, 6-10）：使用预定义的 Excel 模板，适合批量处理结构化数据
自定义工作流路径（本步骤）：上传任意资产，适合非标准场景和自定义工作流

上传自定义资产

使用 UploadInputAsset 接口上传你的原始输入资产。支持的格式包括文本、图片、音频等，单文件大小上限 10 MiB。

cURLcurl -X POST "https://loomloom.shengsuanyun.com/batch/v1/batch/input-assets:upload" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filename": "my_image.png", "content": "base64_encoded_content_here", "contentType": "image/png" }'

响应字段说明

字段	类型	说明
`inputAssetId`	string	资产 ID（如 ia_xxx），用于后续工作流提交
`filename`	string	原始文件名
`mimeType`	string	服务端确认的 MIME 类型
`sizeBytes`	string (int64)	资产大小（字节）
`uploadedAt`	string (int64)	上传时间戳（Unix 秒）

下一步

上传成功后，你会收到一个 inputAssetId。这个 ID 可以在后续自定义工作流提交时使用，替代官方模板中的文件上传。

使用 inputAssetId 提交流程示例

上传资产拿到 inputAssetId 后（例如 ia_abc123），在模板行数据的图片/文件字段中直接填入该 ID：

cURL# 第一步：上传图片资产 curl -X POST "https://loomloom.shengsuanyun.com/batch/v1/batch/input-assets:upload" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"filename": "product.jpg", "content": "base64...", "contentType": "image/jpeg"}' # 返回: {"inputAssetId": "ia_abc123", ...} # 第二步：在模板行数据中引用 inputAssetId curl -X POST "https://loomloom.shengsuanyun.com/batch/v1/templates:submit-rows" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "templateId": "YOUR_TEMPLATE_ID", "rows": [ {"values": {"文本提示词": "生成产品宣传图", "参考图片": "ia_abc123"}} ] }'

字段值为 ia_ 前缀开头时，系统会自动将其识别为已上传资产引用，而不是普通文本 URL。

API 参考 · POST /v1/batch/input-assets:upload

校验数据

提交前先校验，避免正式提交时才发现格式错误。

方式一：上传 Excel 文件校验

cURLcurl -X POST "https://loomloom.shengsuanyun.com/batch/v1/templates/validate" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "template_id=YOUR_TEMPLATE_ID" \ -F "file=@filled_template.xlsx"

方式二：JSON 逐行校验

cURLcurl -X POST "https://loomloom.shengsuanyun.com/batch/v1/templates:validate-rows" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "templateId": "YOUR_TEMPLATE_ID", "rows": [ {"values": {"文本提示词": "一只可爱的猫咪在草地上玩耍", "写作要求": "写实风格，温暖色调"}}, {"values": {"文本提示词": "一座雄伟的山峰", "写作要求": "水墨画风格，留白构图"}} ] }'

字段 key 说明

重要：rows 中 values 的 key 必须使用模板 schema 中的中文字段标签（label），而非英文字段 key。请参考 GET /templates/{templateId}/schema 返回的 sampleRows 中的 key 格式。

响应解读

字段	说明
`valid`	true 表示全部通过
`fileErrors`	文件级错误（如格式不对）
`rowErrors`	行级错误，包含 rowIndex、fieldKey、error

注意

rowIndex 是 1-based（第1行是表头，数据从第2行开始）。如果报错 "第3行 xxx 字段为空"，对应 Excel 的第3行。

API 参考 · POST /v1/templates/validate & /v1/templates:validate-rows

预估费用

提交前看看要花多少钱，余额够不够。

预估成本

cURLcurl -X POST "https://loomloom.shengsuanyun.com/batch/v1/templates:precheck-rows" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "templateId": "YOUR_TEMPLATE_ID", "rows": [ {"values": {"文本提示词": "一只可爱的猫咪在草地上玩耍", "写作要求": "写实风格，温暖色调"}} ] }'

字段	说明
`estimatedTotalCost`	预估总费用（单位：千万分之元）
`balanceCheck.availableBalance`	当前可用余额
`balanceCheck.isSufficient`	true 表示余额充足

费用单位

费用单位是"千万分之元"，即 10000000 = 1元。例如 estimatedTotalCost: 500000 = 0.05元。

API 参考 · POST /v1/templates:precheck-rows

提交任务

数据校验通过、费用预估 OK，正式提交批处理任务。

方式一：上传 Excel 文件提交

cURLcurl -X POST "https://loomloom.shengsuanyun.com/batch/v1/templates/submit" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "template_id=YOUR_TEMPLATE_ID" \ -F "file=@filled_template.xlsx" \ -F "callback_url=https://your-server.com/callback" \ -F "idempotency_key=unique-key-123"

方式二：JSON 逐行提交

cURLcurl -X POST "https://loomloom.shengsuanyun.com/batch/v1/templates:submit-rows" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "templateId": "YOUR_TEMPLATE_ID", "rows": [ {"values": {"文本提示词": "一只可爱的猫咪在草地上玩耍", "写作要求": "写实风格，温暖色调"}}, {"values": {"文本提示词": "一座雄伟的山峰", "写作要求": "水墨画风格，留白构图"}} ], "callbackUrl": "https://your-server.com/callback", "idempotencyKey": "unique-key-123" }'

响应

字段	说明
`runId`	重要！任务运行 ID，后续查询进度、下载结果都要用它
`status`	初始状态（通常是 pending 或 running）
`acceptedAt`	接受时间戳

重要

保存 runId！后面所有查询都靠它。建议存到数据库或日志里。

幂等键

idempotencyKey 可以防止重复提交。同一个 key 多次提交只会创建一次任务。

API 参考 · POST /v1/templates/submit & /v1/templates:submit-rows

跟踪进度

任务提交后是异步执行的，需要轮询查看进度。

查询运行状态

cURLcurl -X GET "https://loomloom.shengsuanyun.com/batch/v1/batch/workflow-runs/{runId}" \ -H "Authorization: Bearer YOUR_API_KEY"

字段	说明
`status`	运行状态：pending / running / completed / failed
`totalTasks`	总任务数
`completedTasks`	已完成数
`failedTasks`	失败数
`actualCost`	实际费用（千万分之元）

查看任务列表

cURLcurl -X GET "https://loomloom.shengsuanyun.com/batch/v1/batch/workflow-runs/{runId}/tasks?status=failed" \ -H "Authorization: Bearer YOUR_API_KEY"

可以按 status 过滤，查看哪些任务失败了以及失败原因。

字段	说明
`taskId`	任务唯一标识
`sourceRowIndex`	对应原始数据行的索引（0-based），可定位到具体哪一行出错
`status`	任务状态：pending / running / completed / failed / cancelled
`errorMessage`	失败原因（仅 status=failed 时有值）
`artifactCount`	该任务产生的产物数量

轮询建议

建议每 5-10 秒轮询一次 GetWorkflowRun，直到 status 变为 completed 或 failed。

API 参考 · GET /v1/batch/workflow-runs/{runId} & /tasks

下载结果

任务完成后，下载生成的产物（图片、文本等）。

获取产物列表

cURLcurl -X GET "https://loomloom.shengsuanyun.com/batch/v1/batch/workflow-runs/{runId}/artifacts" \ -H "Authorization: Bearer YOUR_API_KEY"

字段	说明
`artifacts`	产物数组
`artifactId`	产物 ID
`accessUrl`	短期签名 URL，可直接下载文件
`inlineText`	小文本内容（< 4KB 时直接返回文本）
`sourceRowIndex`	对应原始 Excel 的行号（0-based）
`mimeType`	文件类型（如 image/png）

下载文件

cURLcurl -o output.png "https://xxx.oss.xxx.com/artifact/xxx?signature=xxx"

直接用 accessUrl 下载，无需额外认证。

注意

accessUrl 是短期签名 URL，通常有效期几小时。请尽快下载，过期后需要重新获取。

完成

到这里你就完成了一次完整的 Loomloom 批处理流程！可以继续提交新任务，或者用回调 URL 实现自动化。

API 参考 · GET /v1/batch/workflow-runs/{runId}/artifacts