功能指南

图片生成与编辑

图片是异步任务：提交返回 202 和任务 id，再查询任务拿结果。API Key 需要「图片生成与编辑」权限。

1. 选模型

GET /v1/models?type=image 返回全部图片模型，kind 为 generate 的用来文生图，edit 的用来改图；aspectRatios、resolutions 是可选参数，creditCost 是每张的积分。也可以直接看图片模型。

2. 提交

curl -s -X POST https://sichang.xyz/api/v1/images \
  -H "Authorization: Bearer $SICHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model": "z-image-turbo", "prompt": "清晨湖边的小木屋，水彩风格", "aspectRatio": "16:9"}'

{"job": {"id": "8dc629d6-…", "type": "image", "status": "PROCESSING",
  "credits": {"charged": 10, "refunded": 0}, "outputs": [], …}}

提交即扣费，credits.charged 就是本次扣的积分。aspectRatio、resolution 不传时取该模型的第一个可选值。

3. 拿结果

curl -s "https://sichang.xyz/api/v1/jobs/$JOB_ID?wait=30" -H "Authorization: Bearer $SICHANG_API_KEY"

wait=30 让服务器最多等 30 秒、出结果立即返回。status 是 COMPLETED、FAILED 或 EXPIRED 之一时结束，否则再调一次。完成后 outputs[].downloadUrl 是图片地址，15 分钟内有效；过期了重新查询任务会拿到新地址。

4. 编辑图片

POST /v1/uploads，{"kind": "image", "target": "image", "contentType": "image/png", "size": <字节数>}，拿到 uploadUrl 与 key。
把文件 PUT 到 uploadUrl（Content-Type 与 size 必须和第一步一致）。
提交时选 kind 为 edit 的模型，加 "inputs": [{"key": "<上一步的 key>"}]；改自己以前生成的图，用 {"creationId": "<任务 id>"}。最多 3 张。

幂等、失败与退款

带 Idempotency-Key 的请求重发，会拿回第一次的任务（响应头 Idempotent-Replayed: true），不会重复扣费。
任务失败自动全额退款，credits.refunded 会等于 charged。
提示词最长 2500 字。被内容审核拦下返回 422，不扣费。