API 文档

图片生成是异步接口。创建成功后先返回 task_id，生成结果需要通过任务查询接口或 WebHook 获取。

1. 查询图片模型

curl https://api.picccai.cn/v1/images/models \
  -H "Authorization: Bearer $PICCC_API_KEY"

选择一个 data[].id 作为 model。比例、分辨率、质量和数量应使用该模型返回的可用值。

2. 创建任务

curl https://api.picccai.cn/v1/images/tasks \
  -H "Authorization: Bearer $PICCC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL_ID",
    "prompt": "一只白色陶瓷杯放在浅木桌上，柔和自然光，电商主图，干净背景",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "quality": "standard",
    "n": 1,
    "external_id": "product-10001"
  }'

请求字段

字段	必填	说明
model	是	GET /v1/images/models 返回的模型 id。
prompt	是	图片描述，最多 4000 个字符。
aspect_ratio	否	图片比例，应从模型的 supported_aspect_ratios 中选择。
resolution	否	分辨率，应从 supported_resolutions 中选择。
quality	否	质量档位，应从 supported_qualities 中选择。
n	否	生成数量，默认为 1，不能超过模型的 max_n。
web_search	否	是否启用联网搜索，仅在所选模型支持时生效。
external_id	否	你的业务编号，最长 160 个字符，用于关联订单或任务。
webhook	否	任务完成后的回调配置。

不要自行拼接模型参数。后台配置变化后，不在模型列表范围内的值可能回退到模型默认值。

创建成功

{
  "id": "oat_xxx",
  "task_id": "task_xxx",
  "type": "image",
  "status": "queued",
  "polling_url": "/v1/tasks/task_xxx",
  "created_at": 1783728000000
}

后续查询使用 task_id，不要使用响应中的 id。id 是开放 API 内部的跟踪编号。

同时配置 WebHook

{
  "model": "YOUR_IMAGE_MODEL_ID",
  "prompt": "一张简洁的夏季饮品海报",
  "webhook": {
    "url": "https://your-app.example.com/webhooks/piccc",
    "secret": "replace-with-a-random-secret"
  }
}

WebHook 地址必须使用 HTTPS。签名验证和重试规则见“接收和验证 WebHook”。

积分扣费

任务创建时按模型、分辨率、质量、数量和可选能力计算积分并立即扣除。积分不足时返回 402 insufficient_credits，不会创建任务。