/models读取模型目录和开放状态
Base URL
https://lumyren.com/api/v1Key 与账户权限已接入。生成按空间和模型逐步开放，以实际返回状态为准。
搜索接入文档
查找模型参数、素材上传、任务恢复与账单说明。
从一次报价开始
在工作空间创建 Key，保存到 LUMYREN_API_KEY；将当前空间 ID 保存到 LUMYREN_ACCOUNT_ID。以下请求只计算费用，不创建任务或扣款。
curl "https://lumyren.com/api/v1/accounts/$LUMYREN_ACCOUNT_ID/quotes" \
-H "Authorization: Bearer $LUMYREN_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"model": "z-image/turbo",
"input": {
"model": "z-image/turbo",
"prompt": "A blue ceramic cup on a wooden table",
"size": "1024*1024"
}
}'报价返回 id、saleUsd、estimated 和 expiresAt。生成请求体为 {"quoteId":"报价 id","idempotencyKey":"本次操作的 UUID"}。确认费用后再创建任务，同一个操作始终复用同一个 UUID。
把创作流程交给 AI 助手
下载 Lumyren Skills，让你使用的 AI 助手按模型实际参数准备输入、获取报价、恢复原任务并检查结果。
三个技能覆盖常见创作
Lumyren 通用创作、Seedance 2.5 视频和视频提示词，附带25个商品展示、素材编辑与社媒内容配方。执行工具使用 Node.js 24，无需安装 npm 依赖。
解压后将需要的完整技能文件夹放入所用工具的技能目录，并配置自己的空间 Key。先报价，再按已授权预算提交；安装不会自动生成或扣费。只写视频提示词无需调用生成接口。
配方使用当前模型契约，空间权限与开放状态仍以接口返回为准。上传你选定的素材，作品下载后校验原文件；素材与结果保留24小时。
在 ComfyUI 中创作
把远端模型连入你的画布，保留本地图片处理流程。11个节点支持模型参数、素材上传、报价、任务恢复和作品下载，图片结果可直接连接 ComfyUI 的图像节点。
安装节点包即可开始
将完整节点文件夹放入 ComfyUI 的 custom_nodes 目录并重启，在启动环境中配置自己的空间 Key 和空间 ID。无需下载本地模型权重，Key 不保存在工作流里。
附带文生图、图生视频、多参考视频和多任务四份示例。先运行查看报价，再设置本次金额上限并启用提交；恢复任务时保留原意图名称与参数。
模型选择随安装包提供，实时参数、权限与开放状态以接口为准。素材与结果在服务器保留24小时，请及时下载保存。已在 ComfyUI 0.35.0 与前端 1.51.10 验证导入、导出及原任务恢复。
把模型接入自动化流程
在自行托管的 n8n 中使用 Lumyren Chat、Task Submit 和 Task Status 节点，连接已有的内容、数据与发布流程。
三个节点和三份工作流
下载完整安装包，由实例管理员放入 n8n 节点目录并重启。使用自己的空间 Key 创建 Lumyren API 凭据，再导入对话、文生图或异步视频示例。
示例默认只报价。设置每项创作的金额上限后再启用提交，批量总上限为各项之和；重跑时用相同意图名称恢复原任务。视频可以连接 Wait 节点，稍后继续查询。
已在 n8n 2.40.5 与 Node.js 24 验证导入、执行和重启恢复。当前支持单主机持久记录；模型参数、权限与余额条件以实时接口为准。服务器文件保留24小时。
使用标准客户端
OpenAI Chat 与 Responses 使用 https://lumyren.com/v1；Anthropic Messages 与 Gemini 使用 https://lumyren.com。Gemini API 版本可选 v1 或 v1beta，Messages 使用 2023-06-01 版本。模型使用目录中的完整标识，Key 自动绑定当前空间。
每次新的生成先持久保存一个 UUID，通过 Idempotency-Key 请求头提交。网络重试复用原 UUID 和完整参数，返回同一任务；响应头 x-lumyren-job-id 可用于查询进度。直接调用会预留余额并创建任务，费用按实际用量结算。
直连需要 jobs:write、jobs:read 和 assets:read。公开模型、费率与余额条件满足后才能生成，以接口返回状态为准。查看 SDK 示例与参数范围。
Key 与权限
空间所有者或管理员创建 Key，原文只显示一次。每个 Key 可单独限定操作、模型、每日用量、请求频率与有效期。吊销后立即拒绝新请求，在途任务继续处理。
AuthorizationBearer 你的 LUMYREN_API_KEYContent-Typeapplication/json，原始文件上传除外idempotencyKey创建任务请求体中的 UUID 字段可选权限：models:read、jobs:read、jobs:write、assets:read、assets:write、billing:read。Key 绑定一个空间，不能管理账号密码、充值或创建其他 Key。每日限额按 UTC 提交日统计，含在途预留金额；失败与取消任务释放占用。
接口参考
路径均相对于 Base URL。模型目录可公开读取；任务、文件和账单需要相应 Key 权限。全量目录与实际开放生成的模型范围分别返回。
/models/detail?model=z-image%2Fturbo读取指定模型的参数契约
/accounts/:accountId/quotes提交 model 与 input，获取同参数费用，有效期 5 分钟
/accounts/:accountId/quotes/:quoteId读取已有报价
/accounts/:accountId/jobs提交 quoteId 与 idempotencyKey，预留余额并创建任务
/accounts/:accountId/jobs/:jobId读取任务状态，不重新提交生成
/accounts/:accountId/jobs/:jobId/events订阅任务 SSE 事件，用 Last-Event-ID 断线续读
/accounts/:accountId/jobs/:jobId/language-stream续读已验证的语言文本，需要 assets:read
/accounts/:accountId/jobs读取创作记录，用 before 游标翻页
/accounts/:accountId/jobs/:jobId/cancel取消尚未提交供应商的排队任务
/workflow-templates读取可编辑的多节点计划
/accounts/:accountId/workflows保存计划与创建 UUID，不执行或扣费
/accounts/:accountId/workflows分页读取工作流历史
/accounts/:accountId/workflows/:runId读取节点、尝试与实际扣费
/accounts/:accountId/workflows/:runId/nodes/:nodeKey/quote计算单节点费用，返回 attemptId 和报价
/accounts/:accountId/workflows/:runId/nodes/:nodeKey/confirm使用已保存尝试与 UUID 确认费用并执行此节点
/accounts/:accountId/uploads上传图片、音频或视频原始字节，单文件最大 256 MiB
/accounts/:accountId/assets?job=:jobId读取任务的私有文件列表
/accounts/:accountId/assets/:assetId/content按权限读取文件，GET 支持单段 Range
/accounts/:accountId/wallet读取可用余额和预留余额
/accounts/:accountId/ledger读取账本流水
/accounts/:accountId/model-usage按 UTC 日期查询已完成任务与语言词元
/accounts/:accountId/model-costs按 UTC 日期查询实际模型扣费
任务与重试
创建任务后保存任务 id，通过 SSE 或 GET 详情读取进度。创建请求超时后，可用原 quoteId 和原 idempotencyKey 再次请求，取得同一任务。不要为同一次操作换一个 UUID。
queued等待提交，可取消submitting正在提交供应商submission_unknown提交结果待核对，不重复发送processing供应商正在生成importing正在保存生成结果succeeded结果已保存，费用已结算failed已确认失败，预留余额已释放cancelled排队任务已取消，预留余额已释放billing_review结果或费用需要核对，保留预留金额
submission_unknown 与 billing_review 需要核对。不要自动新建付费任务。通知或连接失败不改变任务结果，先查询原任务再决定后续操作。
实时进度
使用 jobs:read 权限请求任务的 /events 地址，响应为 text/event-stream。job.state 包含 jobId、state、createdAt，每条状态都有递增的 id；终态随后发送 job.complete 并关闭连接。
保存已处理的事件 id，重连时通过 Last-Event-ID 请求头传回，也可用 after 查询参数。连接最长持续 120 秒，空闲时每 12 秒发送心跳。断线后重新连接同一个任务，不要重新创建任务。401、403、404 或 stream.error 的 access_changed 表示需要重新核对访问权限。
curl -N "https://lumyren.com/api/v1/accounts/$LUMYREN_ACCOUNT_ID/jobs/$JOB_ID/events" \
-H "Authorization: Bearer $LUMYREN_API_KEY" \
-H "Last-Event-ID: $LAST_PROCESSED_EVENT_ID"语言任务另有 /language-stream 文本流，使用客户端 languageEvents 或命令行 stream 读取。language.delta 包含已验证的文本与候选序号，language.end 表示文本流结束；最终扣费和作品是否保存，以任务详情或 job.complete 为准。文本流需要 assets:read，查询任务状态和最终扣费还需要 jobs:read；游标与任务状态流分别保存，不混用。
首次订阅时省略 Last-Event-ID。每个账号最多同时打开 8 条连接；网络分包可能拆开一条事件，接收方需按空行解析事件，不能把每个字节块当作完整 JSON。
回调通知
在工作空间的开发者接口中创建接收地址。需要 Key 管理和资源读取权限，每个空间最多启用 5 个地址。支持公网 HTTPS 的 443 端口，不接受跳转、地址内的账号密码、查询参数或片段。
通知覆盖创建地址后该空间的 job.succeeded、job.failed 与 job.cancelled。正文含通知 id、type、createdAt，以及 data 中的 jobId、accountId、model、state，不包含提示词、供应商凭据或文件下载链接。收到成功通知后，用自己的 Key 查询任务与私有文件。
验证来源与去重
创建地址后保存一次显示的 whsec_ 签名密钥。读取原始请求字节，验证 webhook-timestamp 与当前时间相差不超过 300 秒，再用密钥计算 HMAC-SHA256，签名内容为 webhook-id、英文句点、webhook-timestamp、英文句点及原始正文。结果的十六进制字符串前加 v1=，与 webhook-signature 进行恒定时间比较。
下载 Node.js 验签示例。验签通过后，将通知 id 与业务处理写入同一数据库事务，并以唯一约束去重。已处理的有效通知直接返回 2xx。先确认持久接收，再返回成功；通知可能重复送达。
失败与重试
每次投递要求 8 秒内收到 2xx 响应头，最多尝试 6 次，间隔依次为 30 秒、2 分钟、10 分钟、1 小时、3 小时。服务中断恢复后沿用同一通知 id 与正文，重新签名；通知超过 24 小时不再投递。3xx 不跟随跳转，也按失败处理。
投递记录显示状态、次数、HTTP 响应和下次时间。停用地址后停止新通知与排队通知，已发送的请求可能仍会完成。成员移除或团队关闭会停用相应地址；创建者降权期间也停止投递。通知重试不重新生成、不扣余额。
上传与文件
上传请求使用 Content-Type: application/octet-stream、准确的 Content-Length，以及 x-lumyren-upload-id: UUID。发送文件原始字节，不使用 multipart。重试复用同一上传 UUID 和同一文件。
将上传返回的 referenceUrl 填入模型的对应输入字段，再计算报价。上传与模型生成使用同一空间。文件为私有访问，保存 24 小时，到期不可下载；请在到期前保存所需作品。
下载先读取 assets 列表，再带 Key 请求 downloadPath。媒体播放支持单段 Range；HEAD 返回文件长度与类型。
用量与账单
使用 billing:read 权限查询 model-usage 与 model-costs。用量按任务完成时间统计，费用按实际扣账时间统计；充值、预留和人工退款不计入模型消费，词元仅来自已结算语言回执。
必填 start_date 与 end_date 为 YYYY-MM-DD，按 UTC 计算，结束日期不含当天，每次最多180天。group_by[] 支持 model、model_type、api_key，或模型与密钥联合分组；可用 model_ids[]、model_types[] 和 api_key_ids[] 筛选。
每页最多1000组，将 next_page 原样传给 page，沿用原日期和筛选条件继续读取。同一天的分组可能跨页，读完后再汇总；重新查询可查看后来入账的记录。金额以十进制字符串返回，不用浮点累加。下载完整接口说明。
curl -G "https://lumyren.com/api/v1/accounts/$LUMYREN_ACCOUNT_ID/model-costs" \
-H "Authorization: Bearer $LUMYREN_API_KEY" \
--data-urlencode "start_date=2026-09-01" \
--data-urlencode "end_date=2026-09-14" \
--data-urlencode "group_by[]=model"错误处理
错误响应包含 error.code 和 error.requestId。401 表示 Key 无效或已到期，403 表示权限不满足。429 时按 Retry-After 等待。Key 的每分钟限制之外，报价另有每账号 20 次／分钟、上传 30 次／分钟的限制。
402 的 insufficient_balance，或 409 的 api_key_daily_limit、generation_not_open、model_generation_not_open、quote_expired 需要先处理对应条件。参数错误不应原样反复重试。服务错误不代表供应商没有接到任务，应先核对原任务状态。