Keevx 图像生成技能

通过 Keevx API，使用文本提示词（prompt）及可选的参考图像，生成高质量 AI 图像。每次请求可生成一张或多张图像，并支持配置输出质量、宽高比和生成模式。

前提条件

设置环境变量 KEEVX_API_KEY，该密钥需从 https://www.keevx.com/main/home 获取。文档地址：https://docs.keevx.com

export KEEVX_API_KEY="your_api_key_here"

API 接口地址

• 基础 URL：https://api.keevx.com/v1
• 上传图像：POST /figure-resource/upload/file（Content-Type：multipart/form-data）
• 创建任务：POST /image_generate（Content-Type：application/json）
• 查询状态：GET /image_generate/{task_id}
• 鉴权方式：所有接口均使用 Authorization: Bearer $KEEVX_API_KEY
• 来源标识：所有接口均需携带请求头 source: skill

请求参数

• prompt（必填）：生成提示词，最长 1000 字符
• reference_images（可选）：参考图像 URL 数组，最多 5 张，每张不超过 20MB；支持格式：JPG/JPEG/PNG/BMP/WebP/GIF
• module（可选）：生成模式，std（标准模式，默认）或 pro（专业模式）
• generate_count（可选）：生成图像数量，取值范围为 1–8，默认为 1；每张图像对应一个独立的 task ID
• image_quality（可选）：输出图像质量：1K、2K（默认）、4K
• image_ratio（可选）：图像宽高比，默认为 9:16；有效值包括：1:1、3:2、2:3、3:4、4:3、4:5、5:4、9:16、16:9、21:9
• callback_url（可选）：任务完成后的回调通知地址

图像输入处理

用户提供的图像可能是 URL 或本地文件路径，请按以下方式分别处理：

• URL（以 http:// 或 https:// 开头）：可直接用于 reference_images 字段
• 本地文件路径：需先调用上传接口上传，再将响应中返回的 URL 用于 reference_images

上传本地文件

curl --location 'https://api.keevx.com/v1/figure-resource/upload/file' 
  --header 'Authorization: Bearer $KEEVX_API_KEY' 
  --header 'source: skill' 
  --form 'file=@"/path/to/local/image.png"'

响应示例：

{
  "code": 0,
  "success": true,
  "message": { "global": "success" },
  "result": {
    "url": "https://storage.googleapis.com/.../image.png",
    "fileId": "c5a4676a-...",
    "fileName": "image.png"
  }
}

提取响应中 result.url 的值，作为 reference_images 中的图像 URL。若需上传多个本地文件，请逐一上传并收集全部返回的 URL。

快速示例

基础生成（仅提示词）

curl -X POST "https://api.keevx.com/v1/image_generate" 
  -H "Authorization: Bearer $KEEVX_API_KEY" 
  -H "source: skill" 
  -H "Content-Type: application/json" 
  -d '{
    "prompt": "A serene mountain lake at sunset with golden light reflecting on the water",
    "image_quality": "2K",
    "image_ratio": "16:9"
  }'

带参考图像的生成

curl -X POST "https://api.keevx.com/v1/image_generate" 
  -H "Authorization: Bearer $KEEVX_API_KEY" 
  -H "source: skill" 
  -H "Content-Type: application/json" 
  -d '{
    "prompt": "Product shot on white background with soft lighting",
    "reference_images": ["https://example.com/product.jpg"],
    "module": "pro",
    "generate_count": 4,
    "image_quality": "4K",
    "image_ratio": "1:1"
  }'

查询任务状态

curl -X GET "https://api.keevx.com/v1/image_generate/i2is-xxxxxxxx" 
  -H "Authorization: Bearer $KEEVX_API_KEY" 
  -H "source: skill"

响应格式

任务创建成功

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task_ids": ["i2is-a1b2c3d4e5f6", "i2is-g7h8i9j0k1l2"]
  }
}

task_ids 数组中每个元素对应一张生成图像（数量等于 generate_count），需对每个 task ID 单独发起状态查询。

任务查询 —— 生成中

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task_id": "i2is-a1b2c3d4e5f6",
    "status": "GENERATING",
    "image_url": "",
    "thumbnail_url": "",
    "error_message": ""
  }
}

任务查询 —— 成功

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task_id": "i2is-a1b2c3d4e5f6",
    "status": "SUCCEEDED",
    "image_url": "https://storage.googleapis.com/.../image.png",
    "thumbnail_url": "https://storage.googleapis.com/.../thumb.webp",
    "error_message": ""
  }
}

任务查询 —— 失败

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task_id": "i2is-a1b2c3d4e5f6",
    "status": "FAILED",
    "image_url": "",
    "thumbnail_url": "",
    "error_message": "Image generation failed due to content policy"
  }
}

状态值说明

• GENERATING：任务正在处理中
• SUCCEEDED：图像生成成功
• FAILED：生成失败，请检查 error_message 字段内容

错误响应示例

{
  "code": 100001,
  "msg": "Parameter error: prompt is required"
}

回调通知

在创建任务时提供 callback_url 参数，系统将在任务完成后向该地址发送 POST 请求：

{
  "code": 0,
  "msg": "ok",
  "task_type": "image_generate",
  "data": {
    "task_id": "i2is-18e830d27ea041658e4accd576ea7008",
    "status": "SUCCEEDED",
    "image_url": "https://storage.googleapis.com/.../image.png",
    "error_message": ""
  }
}

回调字段说明：

• code：状态码，0 表示成功
• task_type：固定为 image_generate
• data.task_id：任务 ID
• data.status：SUCCEEDED 或 FAILED
• data.image_url：生成图像的 URL（仅成功时存在）
• data.error_message：错误信息（仅失败时存在）

轮询策略

图像生成通常在数分钟内完成。建议轮询间隔为 10 秒，最多重试 60 次（总计约 10 分钟）。若超时仍未完成，可引导用户前往 https://www.keevx.com/main/meta/creations 查看并下载结果。

MAX_RETRIES=60
INTERVAL=10

for i in $(seq 1 $MAX_RETRIES); do
  status=$(curl -s -X GET "$API_BASE/image_generate/$TASK_ID" 
    -H "Authorization: Bearer $KEEVX_API_KEY" 
    -H "source: skill" | jq -r '.data.status')

  if [ "$status" = "SUCCEEDED" ]; then echo "Success"; break
  elif [ "$status" = "FAILED" ]; then echo "Failed"; break; fi

  sleep $INTERVAL
done

echo "Maximum wait time (10 minutes) reached. The task may still be processing."
echo "Please visit https://www.keevx.com/main/meta/creations to check and retrieve the result."

当 generate_count > 1 时，需对上一步响应中返回的每个 task_id 单独进行轮询。

错误码

注意事项

• 生成图像的 URL 仅保留 7 天，请尽快下载
• 单张参考图像最大尺寸为 20MB；支持格式：JPG/JPEG/PNG/BMP/WebP/GIF
• 提示词最大长度：1000 字符
• 若提供超过 5 张参考图像，将自动截断至前 5 张
• 大于 15MB 的图像将在处理前自动压缩为 WebP 格式
• 提示词撰写建议：清晰描述主体对象、风格、构图、光线、氛围与色彩方案，以获得最佳效果