洛辞 API 文档
管理密钥
API 文档/Z Image Pro Uncensored

图像生成 · API v1

Z Image Pro Uncensored 生图 API

通过 Z Image Pro Uncensored 生成图片。本页列出本站当前支持的参数、默认配置和完整调用示例。

POST/api/v1/images/generations
提交成功返回 taskId，不代表图片已生成。每 3–5 秒查询一次任务，图片下载也需携带 API Key。
默认配置参考：0.05 积分。实际消耗以提交前报价和任务结算为准。

快速开始：第一次生成图片

  1. 准备账户与密钥

    登录后在开发者控制台创建 API Key，并确认账户有足够积分。保存完整密钥，关闭后无法再次查看。

  2. 选择模型与参数

    在侧边栏选择一个模型，复制该页的请求示例。将 YOUR_API_KEY 替换为自己的密钥，修改 prompt 为画面描述。先使用示例默认参数和一张图片。

  3. 确认积分报价

    把相同请求发送到 POST /api/v1/images/quote，查看返回的 estimatedPoints。报价不生成图片，也不冻结积分。

  4. 提交生成任务

    发送到 POST /api/v1/images/generations。每次新任务更换 Idempotency-Key；返回 HTTP 202 后保存 taskId，此时图片仍在生成中。

  5. 查询并下载图片

    每 3–5 秒请求一次 GET /api/v1/tasks/{taskId}。将路径中的占位符替换为刚才的任务 ID。任务完成后读取 task.images[].url，拼接本站域名并携带同一密钥下载。

请求与响应示例在桌面端右侧展示，手机端位于参数说明之后。遇到报错？查看常见错误处理。

OpenAI 兼容文生图

客户端的 Base URL 填 https://luocisheng.cn/api/v1，使用本站 API Key，模型填本站模型 ID。仍调用 POST /api/v1/images/generations，以 model 字段提交。成功后直接读取 data[].b64_json。

{
  "model": "z-image-pro",
  "prompt": "一只坐在窗边的猫，柔和的自然光",
  "n": 1
}

请关闭客户端自动重试，并为每次新生成传入独立的 Idempotency-Key。生成等待最多 120 秒；超时后可查询错误中的 task_id，或复用原键及原参数。图片编辑请向 POST /api/v1/images/edits 提交 multipart 表单，使用 image 或 image[] 上传参考图，模型须支持图生图。文生图和图片编辑均可用 stream=true 接收最终 SSE 事件；流式仅支持一张结果，不提供过程预览或遮罩编辑。

创建与使用密钥

  1. 进入开发者控制台的 API 密钥页面，创建密钥并设置便于识别的名称。
  2. 复制完整密钥并保存在自己的服务端环境变量中；页面只展示一次完整密钥。
  3. 在每次 API 请求中携带下面的鉴权头，包括任务查询和图片下载。
  4. 密钥不再使用或意外泄露时，在开发者控制台撤销，并为自己的应用更换新密钥。

所有调用使用请求头 Authorization: Bearer YOUR_API_KEY，JSON 请求还需 Content-Type: application/json。请在自己的服务端使用密钥，不要放入网页、公开代码或 URL。

API Key 只授予图像和视频生成接口访问权限。撤销立即影响后续请求；同账户其他有效密钥仍可查询已提交的 API 任务。

选择模型与请求参数

侧边栏模型文档列出各模型的可用选项。modelId 使用本站业务标识，不要用展示名称替代；也可以携带密钥调用 GET /api/v1/models 获取当前账户可用模型。

以下选项由 Z Image Pro Uncensored 的当前能力配置生成。 支持参考图的图片模型可先直传图片，再通过 referenceImageIds 进行图生图；视频接口支持文字和参考图片输入。参考视频、参考音频、视频编辑和回调暂未开放，具体参数见各视频模型文档。

modelIdstring · 必填

固定为 z-image-pro

promptstring · 必填

描述要生成的画面

numImagesinteger · 可选

示例值为 1；实际可用数量和输出规则由模型决定

aspectRatiostring · 可选

1:1 / 9:16 / 16:9 / 3:4 / 4:3 / 2:3 / 3:2 / 4:5 / 5:4 / 1:2 / 2:1 / 9:21 / 21:9；默认 1:1

imageSizestring · 可选

1K / 2K；不传时使用最高可用清晰度 2K

seedinteger · 可选

随机种子，具体有效范围由模型校验

promptEnhancementboolean · 可选

是否启用模型支持的提示词增强

报价与 API 积分

详细价格表

2 个价格档位
Z Image Pro Uncensored API 调用价格
尺寸提示词增强API 积分 / 次约合人民币 / 次
1K关闭 / 开启（同价）0.025¥0.1725
2K关闭 / 开启（同价）0.05¥0.3450

1 美元 = 1 API 积分。表内为当前 API 售价；人民币仅为汇率换算参考，不改变美元积分扣费。实际以提交前报价及任务结算为准。

表内按 numImages = 1 计费，多份输出按请求数量计算；固定多图模型按一次生成计费，不按返回图片张数重复收费。

参考图片无额外附加费；图片编辑如有独立档位，按表中对应价格计费。

本站固定汇率：1 美元 = 6.9 元。

GET /api/v1/balance 返回 API 账面余额 balance、冻结积分 held 与可用积分 available。API 钱包初始为零，支持在开发者控制台自定义充值。

向 POST /api/v1/images/quote 发送与生成接口相同的参数，获得 estimatedPoints。报价不创建任务、不冻结积分。

1 美元 = 1 API 积分，支持小数。API 使用独立报价和 API 积分，不享受网站会员折扣。请在开发者控制台单独充值，网站原有余额保留且不互通。失败退款规则仍按模型规则执行。提交时冻结报价积分，结束后结算实际消耗。未结算时 chargedPoints 为 null；结算后为实际扣除的积分，失败是否收费沿用网站规则。

查询任务与下载图片

queued 表示排队，processing 表示生成中；这两种状态继续等待。succeeded 表示成功，partial 表示部分成功，failed 表示失败，进入这三种状态后停止轮询。下载前检查 task.images 是否有结果；没有图片时查看错误说明。

请求 GET /api/v1/tasks/{taskId}。任务状态可能为 queued、processing、succeeded、partial 或 failed。部分成功时仍可能返回图片，积分以 settled 和 chargedPoints 为准。

task.images[].url 是本站的相对路径，拼接本站域名后携带相同鉴权请求头下载。API 只能查询当前账户自己的 API 任务；全部创作记录和消耗可在任务日志与积分流水查看。

幂等重试与调用规则

每个新任务使用独立的 Idempotency-Key。网络超时重试时保持幂等键和参数不变，避免重复创建或冻结积分；更改参数会返回 409。幂等键为 8–128 位字母、数字或 ._:-，同账户多个密钥共用幂等范围。删除任务后不能依赖原键防止重复提交。

API Key 接入不受网页会员等级的任务并发上限限制，可同时提交多个任务；任务实际完成时间取决于排队与处理进度。

有效 API Key 的模型查询、报价、提交、任务查询和图片下载不设请求频率上限。建议每 3–5 秒查询一次生成中的任务，避免无效轮询；实际完成时间取决于排队与处理进度。无效密钥的重复认证尝试仍受防滥用保护。

错误处理

400

参数无效，请检查模型能力与字段

401

密钥无效或已撤销

402

积分不足

404

任务或图片不存在，或不属于当前账户

409

幂等键对应的参数冲突

429

无效密钥认证尝试过于频繁

5xx

服务或图片暂不可用，稍后重试

错误响应统一包含 error 与 code。遇到提交超时，先使用原幂等键重试，避免重复付费。