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 CodeDescription200Success400Parameter error401Authentication failed429Rate limit exceeded500Internal server errorBusiness Error CodeDescriptionSolution100001Parameter errorCheck parameter format and required fields100002Validation failedVerify parameter values are within valid ranges530002Image processing errorEnsure image URL is accessible, format supported, size under 20MB530003Task creation failedRetry the request110002Task not foundVerify 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