水彩图片 REST API

异步水彩图片生成与编辑 API 的完整接入指南。

REST API 可以根据文字或上传的源图创建水彩图片。它是异步、无状态的：创建端点立即返回任务，你的应用随后轮询任务直至完成。

Base URL 与 API 密钥

https://www.aiwatercolorgenerator.com

登录并打开设置 → API 密钥。
创建密钥并立即复制；完整密钥只显示一次。
将其保存为服务端密钥，例如 AIWATERCOLOR_API_KEY。

生产密钥以 awg_live_ 开头。不要把密钥放进前端或移动端包、URL、公开仓库或日志。

快速开始

curl https://www.aiwatercolorgenerator.com/api/v1/images/generations \
  -X POST \
  -H "Authorization: Bearer $AIWATERCOLOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: generation-example-001" \
  -d '{
    "prompt": "湖边的一座红色小屋",
    "model": "watercolor-lite",
    "aspect_ratio": "4:3",
    "resolution": "1k"
  }'

API 通常返回 HTTP 202 Accepted 和任务对象：

{
  "id": "task_123",
  "object": "image_task",
  "status": "processing",
  "operation": "generation",
  "model": "watercolor-lite",
  "resolution": "1k",
  "aspect_ratio": "4:3",
  "prompt": "湖边的一座红色小屋",
  "output": [],
  "credits": { "charged": 1, "refunded": 0 },
  "error": null,
  "created_at": "2026-09-15T12:00:00.000Z",
  "completed_at": null,
  "links": { "self": "/api/v1/tasks/task_123" }
}

把响应中的 id 代入任务路径，轮询到 succeeded、failed 或 canceled：

curl https://www.aiwatercolorgenerator.com/api/v1/tasks/task_123 \
  -H "Authorization: Bearer $AIWATERCOLOR_API_KEY"

不要让原始 POST 一直等待图片。Worker 返回响应后，任务仍会异步完成。

通用请求规则

请求头	必填	适用端点	说明
`Authorization: Bearer <API_KEY>`	是	全部	验证账户并确定任务所有者。
`Content-Type: application/json`	是	生成、编辑	JSON 对象，最大 32 KiB。
`Content-Type: multipart/form-data`	是	上传	让 `curl -F` 或 HTTP 客户端自动设置 boundary。
`Content-Length`	是	上传	必须声明有界的 multipart 请求体长度；客户端通常会自动设置。
`Idempotency-Key`	是	生成、编辑	调用方生成的 8–255 字符值。

未知 JSON 字段会被拒绝。每个响应都有 X-Request-Id，排错时请保留；响应使用 Cache-Control: no-store。

幂等与安全重试

首次接受生成/编辑请求通常返回 202。
用相同 key 和相同规范化请求重试，会以 200 返回原任务，不重复扣费。
同一操作中用相同 key 发送不同参数，会返回 409 idempotency_conflict。
key 按 API 密钥和操作隔离；每个新的业务请求应使用新的 UUID 类值。
客户端超时时，应使用完全相同的请求体和 key 重试。
已明确收到 502 provider_submission_failed 时，原 key 仍对应该失败任务；请使用相同请求体和一个新 key 发起新的任务。

模型与积分

所有输出都是水彩风格，不存在 style_preset；每次请求生成一张图片。

`model`	1K	2K	4K	编辑输入上限
`watercolor-lite`	1	4	9	4
`nano-banana-2`	8	12	16	9
`nano-banana-pro`	15	15	30	9
`gpt-image-2`	23	25	43	9

表中数字是每次请求消耗的积分。新任务创建时原子扣费；任务失败或取消会全额退回。公开 API 始终使用账户积分，不使用网站每日免费额度。

resolution：1k、2k、4k。aspect_ratio：auto、1:1、4:3、3:4、16:9、9:16、21:9、9:21。

文生图

`POST /api/v1/images/generations`

字段	类型	必填	默认值	规则
`prompt`	string	是	—	去除首尾空白后 1–4,000 个 Unicode 字符。
`model`	string	否	`watercolor-lite`	上述四个模型之一。
`aspect_ratio`	string	否	`auto`	上述比例之一。
`resolution`	string	否	`1k`	`1k`、`2k` 或 `4k`。

curl https://www.aiwatercolorgenerator.com/api/v1/images/generations \
  -X POST \
  -H "Authorization: Bearer $AIWATERCOLOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0199-generation-landscape-001" \
  -d '{
    "prompt": "薄雾群山倒映在安静的湖面",
    "model": "nano-banana-2",
    "aspect_ratio": "16:9",
    "resolution": "2k"
  }'

HTTP	含义
202	新任务已接受。
200	幂等重放，返回原任务。
400	请求头、JSON、字段或参数无效。
401	API 密钥缺失或无效。
402	积分不足。
409	幂等冲突。
429	达到速率或并发限制。
502	上游拒绝提交。
503	生成或限流服务暂不可用。

上传编辑源图

`POST /api/v1/uploads`

编辑前先上传本地或第三方图片。端点接收 multipart file 字段：非空 JPEG、PNG 或 WebP，最大 10 MiB。服务端检查真实文件签名，不只相信扩展名或 MIME。上传不需要幂等 key。

curl https://www.aiwatercolorgenerator.com/api/v1/uploads \
  -X POST \
  -H "Authorization: Bearer $AIWATERCOLOR_API_KEY" \
  -F "file=@./source-image.png"

HTTP 201 Created：

{
  "id": "upload_123",
  "object": "image_upload",
  "url": "https://cdn.aiwatercolorgenerator.com/api-inputs/.../upload_123.png",
  "content_type": "image/png",
  "size_bytes": 284193
}

把返回的 url 原样传给编辑端点；上传 id 不能替代 URL。

HTTP	含义
201	图片验证并存储成功。
400	文件缺失、为空、超限或格式不支持。
401	API 密钥无效。
429	达到上传或 IP 限制。
500	存储发生意外错误。
503	存储暂不可用。

编辑上传图片

`POST /api/v1/images/edits`

字段	类型	必填	默认值	规则
`prompt`	string	是	—	去除首尾空白后 1–4,000 个字符。
`input_images`	string[]	是	—	Lite 为 1–4 个 URL，其他模型为 1–9 个；每个最长 2,048 字符。
`model`	string	否	`watercolor-lite`	四个支持模型之一。
`aspect_ratio`	string	否	`auto`	支持比例之一。
`resolution`	string	否	`1k`	`1k`、`2k` 或 `4k`。

输入必须是本 API 返回的、位于可信应用存储上的 HTTPS URL。任意外部 URL、带账号密码的 URL、自定义端口和 HTTP URL 都会被拒绝。

curl https://www.aiwatercolorgenerator.com/api/v1/images/edits \
  -X POST \
  -H "Authorization: Bearer $AIWATERCOLOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0199-edit-portrait-001" \
  -d '{
    "prompt": "保留人物和构图，改为柔和的湿画法水彩",
    "input_images": [
      "https://cdn.aiwatercolorgenerator.com/api-inputs/.../upload_123.png"
    ],
    "model": "watercolor-lite",
    "aspect_ratio": "3:4",
    "resolution": "2k"
  }'

响应与文生图端点相同，任务中的 operation 为 "edit"。

查询任务

`GET /api/v1/tasks/{task_id}`

用生成/编辑响应中的 id 替换 {task_id}。任务归账户所有，其他账户查询会得到 404 task_not_found。

状态	终态	含义
`queued`	否	已创建但尚未提交。
`processing`	否	已提交并正在处理。
`succeeded`	是	`output` 中有结果 URL。
`failed`	是	查看 `error.code`，积分已退回。
`canceled`	是	积分已退回。

建议每 2–5 秒轮询一次；进入终态后停止。遇到 429 或临时 5xx 时使用退避。

完整任务字段

字段	类型	说明
`id`	string	用于轮询 URL 的公开任务 ID。
`object`	`"image_task"`	固定对象类型。
`status`	string	上述五种状态之一。
`operation`	`"generation"` / `"edit"`	创建任务的操作。
`model`	string / null	公开模型标识。
`resolution`	string / null	计费分辨率。
`aspect_ratio`	string / null	请求的宽高比。
`prompt`	string	调用方原始提示词；不返回内部指令。
`output`	array	成功前通常为空；元素含 `url`、`content_type`。
`credits`	object	整数 `charged` 和 `refunded`。
`error`	object / null	失败时仅包含稳定的公开 `code`。
`created_at`	ISO 8601 string	创建时间。
`completed_at`	ISO 8601 string / null	进入终态的时间。
`links.self`	string	相对轮询 URL。

{
  "id": "task_123",
  "object": "image_task",
  "status": "succeeded",
  "operation": "generation",
  "model": "watercolor-lite",
  "resolution": "1k",
  "aspect_ratio": "4:3",
  "prompt": "湖边的一座红色小屋",
  "output": [
    {
      "url": "https://cdn.aiwatercolorgenerator.com/api-results/.../0.png",
      "content_type": "image/png"
    }
  ],
  "credits": { "charged": 1, "refunded": 0 },
  "error": null,
  "created_at": "2026-09-15T12:00:00.000Z",
  "completed_at": "2026-09-15T12:00:12.000Z",
  "links": { "self": "/api/v1/tasks/task_123" }
}

已接受的任务也可能稍后失败。此时轮询仍返回 HTTP 200，但 status 为 failed、output 为空、积分已退款，并包含例如：

{
  "error": { "code": "generation_failed" },
  "credits": { "charged": 1, "refunded": 1 }
}

HTTP 错误

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "model is not supported.",
    "param": "model",
    "request_id": "req_123"
  }
}

程序应判断稳定的 code，不要解析 message。param 指向相关字段/请求头或为 null；request_id 同时出现在 X-Request-Id。

HTTP	常见 code	处理方式
400	`invalid_content_type`、`invalid_json`、`request_too_large`、`invalid_idempotency_key`	修正编码或请求头。
400	`unknown_parameter`、`invalid_parameter`、`unsupported_model`	修正或删除 `param` 指向的字段。
400	`too_many_input_images`、`untrusted_image_url`	减少输入或使用上传返回的 URL。
400	`missing_file`、`file_too_large`、`request_length_required`、`unsupported_image_type`	修正上传文件或请求头。
401	`invalid_api_key`	使用有效 Bearer 密钥。
402	`insufficient_credits`	增加积分或降低配置。
404	`task_not_found`	检查任务 ID 和账户。
409	`idempotency_conflict`	使用原请求体或新 key。
429	`rate_limit_exceeded`	按 `Retry-After` 等待。
429	`concurrent_task_limit`	等待运行中的任务结束。
500	`internal_error`	退避重试并保留 `request_id`。
502	`provider_submission_failed`	稍后用相同请求体和新 key 重试。
503	`provider_unavailable`、`storage_unavailable`、`rate_limit_unavailable`	稍后重试。

速率与并发限制

范围	限制
每个客户端 IP，所有端点合计	60 次/分钟
每个 API 密钥，生成与编辑合计	10 次/分钟
每个 API 密钥，上传	10 次/分钟
每个 API 密钥，任务查询	120 次/分钟
每个账户，`queued` + `processing`	3 个并发任务

HTTP 429 带有以秒为单位的 Retry-After。IP 与 API 密钥限制彼此独立。

生产接入清单

仅从服务端调用，并从密钥管理服务读取 API Key。
保存幂等 key 和任务 id，让进程重启后仍能继续。
每 2–5 秒轮询；终态停止；429 和临时 5xx 使用退避。
记录 request ID，不记录 API Key 或私有源图内容。
把 code 当作稳定值，把 message 当作诊断文本。
如果需要独立保留策略，把成功输出复制到自己的存储。

机器可读定义

OpenAPI 3.1 文档供代码生成器、Schema 工具和自动化客户端使用。本页面是面向人的接入手册，补充了工作流、重试、计费、限制和排错说明。