Keevx Image-to-Video Skill

Convert images to high-quality videos via the Keevx API.

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_to_video (Content-Type: application/json)
• Query status: GET /image_to_video/{task_id}
• Auth: All endpoints use Authorization: Bearer $KEEVX_API_KEY
• Source identifier: All endpoints require the source: skill Header

Model Selection

Model Selection Guide

• Choose Model V: When audio is needed, 4K resolution required, single or multi-image input, high quality requirements
• Choose Model KL: When multiple reference images are available (2-7), multi-angle showcase needed, product demo videos

Model-Specific Request Bodies

Model V

{
  "model": "V",
  "prompt": "Video description (required, max 1000 chars)",
  "image_url": "https://... (required for single-image mode)",
  "reference_images": ["https://..."],
  "aspect_ratio": "16:9",
  "aspect_resolution": "720p | 1080p | 4k",
  "duration": 4,
  "generate_audio": true,
  "generate_count": 1
}

Model KL

{
  "model": "KL",
  "prompt": "Video description (required)",
  "reference_images": ["https://..."],
  "aspect_ratio": "16:9",
  "aspect_resolution": "720p | 1080p",
  "duration": 5,
  "generate_count": 1
}

Image Input Handling

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

• URL (starts with http:// or https://): Use directly as image_url or 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 example:

{
  "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 as image_url or reference_images. For multiple local files, upload each one and collect all URLs.

Quick Examples

Single Image Generation (Model V)

curl -X POST "https://api.keevx.com/v1/image_to_video" \
  -H "Authorization: Bearer $KEEVX_API_KEY" \
  -H "source: skill" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "V",
    "prompt": "Waves crashing on the beach at sunset",
    "image_url": "https://example.com/beach.jpg",
    "aspect_ratio": "16:9",
    "aspect_resolution": "1080p",
    "duration": 6,
    "generate_audio": true
  }'

Multi-Reference Image Generation (Model KL)

curl -X POST "https://api.keevx.com/v1/image_to_video" \
  -H "Authorization: Bearer $KEEVX_API_KEY" \
  -H "source: skill" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "KL",
    "prompt": "City night timelapse, neon lights flickering",
    "reference_images": [
      "https://example.com/city1.jpg",
      "https://example.com/city2.jpg",
      "https://example.com/city3.jpg"
    ],
    "aspect_ratio": "16:9",
    "aspect_resolution": "1080p",
    "duration": 10,
    "generate_count": 2
  }'

Query Task Status

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

Response Format

Task Created Successfully

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task_ids": ["i2v-d6b6472bcf724d0399e06d1390cb964e"]
  }
}

Task Query Success

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task_id": "i2v-d6b6472bcf724d0399e06d1390cb964e",
    "status": "SUCCEEDED",
    "video_url": "https://storage.googleapis.com/.../sample_0.mp4",
    "thumbnail_url": "https://storage.googleapis.com/.../thumbnail.webp",
    "error_message": "",
    "duration": 6,
    "width": 1920,
    "height": 1080
  }
}

Status Values

PENDING (queued) / PROCESSING (in progress) / SUCCEEDED (completed) / FAILED (failed)

Failure Response

{
  "code": 100001,
  "msg": "Parameter error: prompt cannot be empty"
}

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_to_video",
  "data": {
    "task_id": "i2v-d6b6472bcf724d0399e06d1390cb964e",
    "status": "SUCCEEDED",
    "video_url": "https://storage.googleapis.com/.../sample_0.mp4",
    "thumbnail_url": "https://storage.googleapis.com/.../thumbnail.webp",
    "error_message": ""
  }
}

Polling Strategy

Video generation may take up to 20 minutes. Recommended: 30-second intervals, max 40 retries.

MAX_RETRIES=40
INTERVAL=30

for i in $(seq 1 $MAX_RETRIES); do
  status=$(curl -s -X GET "$API_BASE/image_to_video/$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

Error Codes

Notes

• Generated video/thumbnail URLs are retained for 7 days only; download promptly
• Max image size: 20MB, supported formats: JPG/PNG/WebP
• Max prompt length: 1000 characters
• 429 error: retry after 30s; 500 error: retry after 10s; network error: retry immediately, max 3 times
• Prompt tips: describe subject, scene, action, mood; include visual details (lighting, color, texture)
• Narration script: to add narration to the video, use Speak "narration content" in the prompt, e.g. Speak "Welcome to our channel"
• Image tips: use high-resolution, subject-focused, evenly-lit, well-composed images