鉴权与创建任务
所有请求使用 Authorization: Bearer YOUR_PUREAM_API_KEY。POST 请求使用 Content-Type: application/json。
POST https://puream.cn/api/ai/grok-image/v1/images/generations
请求参数
prompt：必填字符串，去除首尾空格后为1–4000字符。aspect_ratio：可选，默认1:1，支持1:1、16:9、9:16、3:2、2:3、4:3、3:4。size 为比例的兼容字段；支持1024x1024、1536x1024、1024x1536、1792x1024、1024x1792别名。reference_images：可选URL数组，最多3张公开可访问且通过安全校验的图片；images、image为兼容入口。单次生成1张图片，模型及分辨率由服务端固定，无需传model、n或resolution。
{
"prompt": "一只白猫坐在窗边，柔和自然光",
"aspect_ratio": "9:16",
"reference_images": []
}幂等提交
同一次业务请求重试请复用同一 Idempotency-Key，不要更换键重复提交。拿到task_id后只查询该任务。
Idempotency-Key: your-unique-request-id
查询任务
使用创建返回的task_id和同一账号API Key。处理中返回HTTP 202，终态返回HTTP 200。每3–5秒查询一次；网络断开不代表生成失败，不要重新创建。
GET https://puream.cn/api/ai/grok-image/tasks/{task_id}读取结果
status为running时继续查询；succeeded时从data[0].url或result.images[0].url读取图片，data同时包含width、height；failed时查看error/message。HTTP 200也可能是failed，必须检查status。pending_upstream_confirmation=true表示上游结果尚未确认，继续查询原任务。
{
"task_id": "your_task_id",
"status": "succeeded",
"success": true,
"data": [
{
"url": "https://puream.cn/uploads/ai-images/your_task_id.png",
"width": 1024,
"height": 1024
}
],
"result": {
"images": [
{
"url": "https://puream.cn/uploads/ai-images/your_task_id.png"
}
]
}
}计费与错误
费用为当前后台配置的基础生图价格加每张参考图0.10元。创建预冻结、成功结算、明确失败退回；最终以响应billing为准。余额不足返回INSUFFICIENT_BALANCE；提示词、比例、参考图数量错误分别为PROMPT_INVALID、ASPECT_RATIO_INVALID、REFERENCE_IMAGES_LIMIT；任务不存在或不属于当前账号返回404 TASK_NOT_FOUND。