/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。
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读取创作记录，用 before 游标翻页
/accounts/:accountId/jobs/:jobId/cancel取消尚未提交供应商的排队任务
/accounts/:accountId/uploads上传图片、音频或视频原始字节，单文件最大 256 MiB
/accounts/:accountId/assets?job=:jobId读取任务的私有文件列表
/accounts/:accountId/assets/:assetId/content按权限读取文件，GET 支持单段 Range
/accounts/:accountId/wallet读取可用余额和预留余额
/accounts/:accountId/ledger读取账本流水
任务与重试
创建任务后保存任务 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"首次订阅时省略 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 填入模型的对应输入字段，再计算报价。上传与模型生成使用同一空间。文件为私有访问，保存 72 小时，到期不可下载；请在到期前保存所需作品。
下载先读取 assets 列表，再带 Key 请求 downloadPath。媒体播放支持单段 Range；HEAD 返回文件长度与类型。
错误处理
错误响应包含 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 需要先处理对应条件。参数错误不应原样反复重试。服务错误不代表供应商没有接到任务，应先核对原任务状态。