鉴权

所有需鉴权的接口在 Header 携带 X-API-Key。在控制台「API KEY」页面创建 KEY。

X-API-Key: ak_xxxxxxxxxxxxxxxx

上传图片

multipart/form-data，字段 file，≤10MB，jpg/png/webp

{
  "code": 0,
  "data": { "url": "https://.../up_xxx.jpg" }
}

生成头像（异步）

{
  "image": "https://.../your-photo.jpg",
  "sub_user_id": "user_123",
  "style_id": 1,
  "color_id": 2,
  "shape_id": 1,
  "is_public": true
}

返回 record_id，配合查询接口轮询结果

上传即生成（同步，推荐）

multipart/form-data：file 为图片文件（≤10MB，jpg/png/webp），其余参数以表单字段提交（style_id/color_id/shape_id/is_public/sub_user_id）。无需先上传再轮询，一次请求直接返回头像地址。生成约需数秒~数十秒，客户端超时请设 ≥120s。

curl -X POST https://你的域名/api/v1/avatar/generate-sync \
  -H "X-API-Key: ak_xxxx" \
  -F "file=@/path/to/photo.jpg" \
  -F "style_id=1" \
  -F "is_public=1"

{
  "code": 0,
  "data": {
    "record_id": 100,
    "status": "success",
    "avatar_id": 1001,
    "url": "https://.../result.png",
    "thumb_url": "https://.../thumb.png",
    "audit_status": "approved",
    "cost_points": 10,
    "remaining_points": 90
  }
}

生成失败会自动退还积分并返回 502；审核驳回时 audit_status=rejected 且积分退还。

查询生成结果

{
  "code": 0,
  "data": {
    "record_id": 100,
    "status": "success",
    "avatar_id": 1001,
    "url": "https://.../result.png",
    "thumb_url": "https://.../thumb.png",
    "cost_points": 10
  }
}

其他接口

错误码