# Z Image Pro Uncensored API 文档

所有注册用户可使用，使用独立 API 价格与积分余额，不享受网站会员折扣。API Key 接入不受网页会员等级的任务并发上限限制，有效密钥调用不设请求频率上限。支持文生图、部分图片模型的图生图、文生视频和参考图生视频；部分视频模型支持参考视频、参考音频与视频编辑，具体以各模型文档为准；回调暂未开放。视频接口为 /api/v1/videos/generations 和 /api/v1/videos/quote，结果位于 task.videos[].url。

## 鉴权

在开发者控制台创建密钥，请求头为 Authorization: Bearer YOUR_API_KEY。仅在自己的服务端使用密钥。

## 模型参数

模型 ID：z-image-pro
默认配置参考价格：0.05 积分
比例：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
尺寸：1K / 2K
质量：由模型默认配置决定

## 提交生图

POST https://luocisheng.cn/api/v1/images/generations
Content-Type: application/json
Idempotency-Key: image-demo-0001

```json
{
  "modelId": "z-image-pro",
  "prompt": "一只坐在窗边的猫，柔和的自然光",
  "numImages": 1,
  "aspectRatio": "1:1",
  "imageSize": "2K"
}
```

成功返回 HTTP 202 和 taskId。提交时冻结积分，结束后结算。

## OpenAI 兼容文生图

Base URL：https://luocisheng.cn/api/v1。仍使用本站 API Key 和 API 钱包。向同一个 images/generations 地址发送 `model`（本站模型 ID）、`prompt` 和可选 `n`，最多等待生成结算 120 秒，成功返回 HTTP 200 和 `data[].b64_json`。选填 `response_format: "url"` 时返回本站下载地址，下载仍需 Bearer 鉴权。不传 `size` 或传 `auto` 使用模型默认值；`1024x1024`、`1536x1024`、`1024x1536`、`1792x1024`、`1024x1792` 映射为对应画幅和 1K 档，实际像素由模型决定。图片编辑使用 POST /api/v1/images/edits，以 multipart/form-data 提交同样的模型和提示词，使用 image 或 image[] 上传 PNG、JPEG、WebP 参考图，单张最多 5 MiB，最多 4 张且受模型限制。暂不支持遮罩或远程文件。生成与编辑可传 stream=true（n=1、partial_images=0），仅在结算后发送最终 SSE 事件，不发送过程预览。关闭客户端自动重试；提交时带 `Idempotency-Key`，超时后查询返回的 `task_id`，或复用原键和原请求。

## API 余额

GET https://luocisheng.cn/api/v1/balance 返回 balance、held、available，单位为 API 积分。API 与网站积分互不通用，API 从零开始，需在开发者控制台单独充值。

## 详细价格表

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 元。


## 图像清晰度

imageSize 不传时默认使用该模型支持的最高 K 档，按对应尺寸售价计费；显式传入时使用指定档位。

## 报价

POST https://luocisheng.cn/api/v1/images/quote，参数与生成接口相同。estimatedPoints 是报价积分。

## 查询与下载

GET https://luocisheng.cn/api/v1/tasks/{taskId}
每 3–5 秒查询一次；task.images[].url 是本站相对图片地址，下载同样需要鉴权请求头。
settled 为 true 时 chargedPoints 是实际扣费；未结算时为 null。状态包括 queued、processing、succeeded、partial、failed。

## 重试与错误

网络超时复用同一 Idempotency-Key 和相同参数，避免重复创建任务或冻结积分。幂等键为 8–128 位字母、数字或 ._:-。修改参数返回 409；删除任务后原键不再提供防重保证。
有效 API Key 的模型查询、报价、提交、任务查询和下载不设请求频率上限。无效密钥的重复认证尝试仍有防滥用保护。
错误格式为 {"error":"错误说明","code":"ERROR_CODE"}。400 参数无效，401 密钥无效，402 积分不足，404 资源不可访问，409 幂等冲突，429 无效密钥认证尝试过于频繁，5xx 服务暂不可用。