keevx-image-generate

Use the Keevx API to generate images from prompts and reference images. Supports standard and professional modes, multiple quality levels (1K/2K/4K), various aspect ratios, and batch generation. Use this skill when the user needs to: (1) Generate images from text prompts (2) Create AI images with reference images (3) Batch image generation (4) Query image generation task status. Keywords: image generate, Keevx, AI image, text to image.

baidu-xiling@baidu-xiling

Install

openclaw skills install @baidu-xiling/keevx-image-generate

Keevx Image Generate Skill

Generate high-quality AI images via the Keevx API using text prompts and optional reference images. Each request generates one or more images with configurable quality, ratio, and mode.

Prerequisites

Set the environment variable KEEVX_API_KEY, obtained from https://www.keevx.com/main/home. Documentation: https://docs.keevx.com

bash

export KEEVX_API_KEY="your_api_key_here"

API Endpoints

Base URL: https://api.keevx.com/v1
Upload image: POST /figure-resource/upload/file (Content-Type: multipart/form-data)
Create task: POST /image_generate (Content-Type: application/json)
Query status: GET /image_generate/{task_id}
Auth: All endpoints use Authorization: Bearer $KEEVX_API_KEY
Source identifier: All endpoints require the source: skill Header

Request Parameters

prompt (required): Generation prompt, max 1000 characters
reference_images (optional): Array of reference image URLs, max 5 images, each under 20MB. Supported formats: JPG/JPEG/PNG/BMP/WebP/GIF
module (optional): Generation mode, std (standard, default) or pro (professional)
generate_count (optional): Number of images to generate, 1-8, default 1. Each image produces a separate task ID
image_quality (optional): Output quality: 1K, 2K (default), 4K
image_ratio (optional): Aspect ratio, default 9:16. Valid values: 1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
callback_url (optional): Callback URL for task completion notification

Image Input Handling

User-provided images may be URLs or local file paths, handle accordingly:

URL (starts with http:// or https://): Use directly in reference_images
Local file path: Upload via the upload endpoint first, then use the returned URL

Upload Local File

bash

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"'

Response:

json

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

Extract the image URL from result.url for use in reference_images. For multiple local files, upload each one and collect all URLs.

Quick Examples

Basic Generation (Prompt Only)

bash

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"
  }'

Generation with Reference Images

bash

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"
  }'

Query Task Status

bash

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

Response Format

Task Created Successfully

json

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

The task_ids array contains one ID per generated image (count equals generate_count). Query each ID individually.

Task Query - Generating

json

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

Task Query - Succeeded

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": ""
  }
}

Task Query - Failed

json

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

Status Values

GENERATING: Task is in progress
SUCCEEDED: Image generated successfully
FAILED: Generation failed, check error_message

Error Response

json

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

Callback Notification

Provide callback_url when creating a task. The system will send a POST request to that URL upon task completion:

json

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

Callback field descriptions:

code: Status code, 0 indicates success
task_type: Fixed as image_generate
data.task_id: Task ID
data.status: SUCCEEDED or FAILED
data.image_url: Generated image URL (on success)
data.error_message: Error message (on failure)

Polling Strategy

Image generation typically completes within a few minutes. Recommended: 10-second intervals, max 60 retries (up to 10 minutes). If timeout is reached, direct the user to https://www.keevx.com/main/meta/creations to retrieve the result.

bash

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."

When generate_count > 1, poll each task_id from the response individually.

Error Codes

HTTP Status Code	Description
200	Success
400	Parameter error
401	Authentication failed
429	Rate limit exceeded
500	Internal server error

Business Error Code	Description	Solution
100001	Parameter error	Check parameter format and required fields
100002	Validation failed	Verify parameter values are within valid ranges
530002	Image processing error	Ensure image URL is accessible, format supported, size under 20MB
530003	Task creation failed	Retry the request
110002	Task not found	Verify task_id is correct

Notes

Generated image URLs are retained for 7 days only; download promptly
Max reference image size: 20MB per image, supported formats: JPG/JPEG/PNG/BMP/WebP/GIF
Max prompt length: 1000 characters
Reference images exceeding 5 will be silently truncated to 5
Images over 15MB are automatically compressed to WebP before processing
Prompt tips: describe subject, style, composition, lighting, mood, and color palette for best results

keevx-image-generate

Install

Keevx Image Generate Skill

Prerequisites

API Endpoints

Request Parameters

Image Input Handling

Upload Local File

Quick Examples

Basic Generation (Prompt Only)

Generation with Reference Images

Query Task Status

Response Format

Task Created Successfully

Task Query - Generating

Task Query - Succeeded

Task Query - Failed

Status Values

Error Response

Callback Notification

Polling Strategy

Error Codes

Notes

Related skills