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

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

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:

{
  "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)

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

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

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

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

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

Task Query - Succeeded

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

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

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

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

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

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