Keevx 图像生成技能

通过 Keevx API 使用文本提示和可选的参考图像生成高质量的 AI 图像。每个请求可生成一张或多张图像，支持配置质量、比例和模式。

前提条件

设置环境变量 KEEVXAPIKEY，从 https://www.keevx.com/main/home 获取。文档：https://docs.keevx.com

bash
export KEEVXAPIKEY=yourapikey_here

API 端点

• - 基础 URL：https://api.keevx.com/v1
• 上传图像：POST /figure-resource/upload/file（Content-Type：multipart/form-data）
• 创建任务：POST /imagegenerate（Content-Type：application/json）
• 查询状态：GET /imagegenerate/{taskid}
• 认证：所有端点使用 Authorization: Bearer $KEEVXAPI_KEY
• 来源标识：所有端点需要 source: skill 请求头

请求参数

• - prompt（必填）：生成提示，最多 1000 个字符
• referenceimages（可选）：参考图像 URL 数组，最多 5 张图像，每张不超过 20MB。支持的格式：JPG/JPEG/PNG/BMP/WebP/GIF
• module（可选）：生成模式，std（标准，默认）或 pro（专业）
• generatecount（可选）：生成图像数量，1-8，默认为 1。每张图像生成一个独立的任务 ID
• imagequality（可选）：输出质量：1K、2K（默认）、4K
• imageratio（可选）：宽高比，默认为 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 或本地文件路径，需相应处理：

• - URL（以 http:// 或 https:// 开头）：直接在 reference_images 中使用
• 本地文件路径：先通过上传端点上载，然后使用返回的 URL

上传本地文件

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

响应：

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

从 result.url 中提取图像 URL，用于 reference_images。对于多个本地文件，逐个上传并收集所有 URL。

快速示例

基础生成（仅提示词）

bash
curl -X POST https://api.keevx.com/v1/image_generate \
-H Authorization: Bearer $KEEVXAPIKEY \
-H source: skill \
-H Content-Type: application/json \
-d {
prompt: 日落时分宁静的山间湖泊，金色光芒倒映在水面上,
image_quality: 2K,
image_ratio: 16:9
}

带参考图像的生成

bash
curl -X POST https://api.keevx.com/v1/image_generate \
-H Authorization: Bearer $KEEVXAPIKEY \
-H source: skill \
-H Content-Type: application/json \
-d {
prompt: 白色背景上的产品拍摄，柔和光线,
reference_images: [https://example.com/product.jpg],
module: pro,
generate_count: 4,
image_quality: 4K,
image_ratio: 1:1
}

查询任务状态

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

响应格式

任务创建成功

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

taskids 数组包含每张生成图像对应的一个 ID（数量等于 generatecount）。需逐个查询每个 ID。

任务查询 - 生成中

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

任务查询 - 成功

json
{
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:
}
}

任务查询 - 失败

json
{
code: 0,
msg: ok,
data: {
task_id: i2is-a1b2c3d4e5f6,
status: FAILED,
image_url: ,
thumbnail_url: ,
error_message: 图像生成因内容策略失败
}
}

状态值

• - GENERATING：任务进行中
• SUCCEEDED：图像生成成功
• FAILED：生成失败，请检查 error_message

错误响应

json
{
code: 100001,
msg: 参数错误：prompt 为必填项
}

回调通知

创建任务时提供 callback_url。系统将在任务完成时向该 URL 发送 POST 请求：

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

回调字段说明：

• - code：状态码，0 表示成功
• tasktype：固定为 imagegenerate
• data.taskid：任务 ID
• data.status：SUCCEEDED 或 FAILED
• data.imageurl：生成的图像 URL（成功时）
• data.error_message：错误信息（失败时）

轮询策略

图像生成通常在几分钟内完成。建议：10 秒间隔，最多重试 60 次（最多 10 分钟）。如果超时，引导用户访问 https://www.keevx.com/main/meta/creations 获取结果。

bash
MAX_RETRIES=60
INTERVAL=10

for i in $(seq 1 $MAX_RETRIES); do
status=$(curl -s -X GET $APIBASE/imagegenerate/$TASK_ID \
-H Authorization: Bearer $KEEVXAPIKEY \
-H source: skill | jq -r .data.status)

if [ $status = SUCCEEDED ]; then echo 成功; break
elif [ $status = FAILED ]; then echo 失败; break; fi

sleep $INTERVAL
done

echo 已达到最大等待时间（10 分钟）。任务可能仍在处理中。
echo 请访问 https://www.keevx.com/main/meta/creations 查看并获取结果。

当 generatecount > 1 时，需逐个轮询响应中的每个 taskid。