Skip to main content
POST
/
v1
/
image_to_video
Create Image to Video Task
curl --request POST \
  --url https://api.keevx.com/v1/image_to_video \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "V",
  "prompt": "A golden retriever running in the grass, sunny day, cinematic lighting",
  "aspect_ratio": "16:9",
  "aspect_resolution": "1080p",
  "duration": 6,
  "image_url": "https://example.com/start_frame.jpg",
  "reference_images": [
    "https://example.com/ref1.jpg",
    "https://example.com/ref2.jpg"
  ],
  "generate_audio": true,
  "generate_count": 1,
  "callback_url": "https://your-server.com/callback"
}
'
import requests

url = "https://api.keevx.com/v1/image_to_video"

payload = {
"model": "V",
"prompt": "A golden retriever running in the grass, sunny day, cinematic lighting",
"aspect_ratio": "16:9",
"aspect_resolution": "1080p",
"duration": 6,
"image_url": "https://example.com/start_frame.jpg",
"reference_images": ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"],
"generate_audio": True,
"generate_count": 1,
"callback_url": "https://your-server.com/callback"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'V',
prompt: 'A golden retriever running in the grass, sunny day, cinematic lighting',
aspect_ratio: '16:9',
aspect_resolution: '1080p',
duration: 6,
image_url: 'https://example.com/start_frame.jpg',
reference_images: ['https://example.com/ref1.jpg', 'https://example.com/ref2.jpg'],
generate_audio: true,
generate_count: 1,
callback_url: 'https://your-server.com/callback'
})
};

fetch('https://api.keevx.com/v1/image_to_video', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.keevx.com/v1/image_to_video",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'V',
'prompt' => 'A golden retriever running in the grass, sunny day, cinematic lighting',
'aspect_ratio' => '16:9',
'aspect_resolution' => '1080p',
'duration' => 6,
'image_url' => 'https://example.com/start_frame.jpg',
'reference_images' => [
'https://example.com/ref1.jpg',
'https://example.com/ref2.jpg'
],
'generate_audio' => true,
'generate_count' => 1,
'callback_url' => 'https://your-server.com/callback'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api.keevx.com/v1/image_to_video"

payload := strings.NewReader("{\n \"model\": \"V\",\n \"prompt\": \"A golden retriever running in the grass, sunny day, cinematic lighting\",\n \"aspect_ratio\": \"16:9\",\n \"aspect_resolution\": \"1080p\",\n \"duration\": 6,\n \"image_url\": \"https://example.com/start_frame.jpg\",\n \"reference_images\": [\n \"https://example.com/ref1.jpg\",\n \"https://example.com/ref2.jpg\"\n ],\n \"generate_audio\": true,\n \"generate_count\": 1,\n \"callback_url\": \"https://your-server.com/callback\"\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.keevx.com/v1/image_to_video")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"V\",\n \"prompt\": \"A golden retriever running in the grass, sunny day, cinematic lighting\",\n \"aspect_ratio\": \"16:9\",\n \"aspect_resolution\": \"1080p\",\n \"duration\": 6,\n \"image_url\": \"https://example.com/start_frame.jpg\",\n \"reference_images\": [\n \"https://example.com/ref1.jpg\",\n \"https://example.com/ref2.jpg\"\n ],\n \"generate_audio\": true,\n \"generate_count\": 1,\n \"callback_url\": \"https://your-server.com/callback\"\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.keevx.com/v1/image_to_video")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"V\",\n \"prompt\": \"A golden retriever running in the grass, sunny day, cinematic lighting\",\n \"aspect_ratio\": \"16:9\",\n \"aspect_resolution\": \"1080p\",\n \"duration\": 6,\n \"image_url\": \"https://example.com/start_frame.jpg\",\n \"reference_images\": [\n \"https://example.com/ref1.jpg\",\n \"https://example.com/ref2.jpg\"\n ],\n \"generate_audio\": true,\n \"generate_count\": 1,\n \"callback_url\": \"https://your-server.com/callback\"\n}"

response = http.request(request)
puts response.read_body
{
  "code": 0,
  "msg": "ok",
  "data": {
    "task_ids": [
      "i2v-d6b6472bcf724d0399e06d1390cb964e",
      "i2v-fc654817587e435e937f1e1b80366c00"
    ]
  }
}
{
"code": 100001,
"msg": "<string>"
}

Detailed Model Parameter Rules

Depending on the value of model, the required status and valid ranges for parameters are as follows:
Name: Standard Model-Start & End Frame VideoFeatures: Supports audio, multiple resolutions, and three image input modes.
ParameterRequiredDescription
promptYesLimited to 1000 characters.
image_urlNoRequired for Start-Frame Mode.
end_image_urlNoSupports end frame upload.
reference_imagesNoRequired for Multi-Image Mode. (Max 3 images)
aspect_resolutionYesSupports 720p, 1080p, 4k.
durationYesSingle-image: 4, 6, 8s; Multi-image: fixed at 8s.
generate_audioNoSupports audio configuration.

end_image_url bad case Notes

End frame aspect ratio should match start frame. Mismatch reduces quality.

Callback Notification

After the video generation task is processed, the service will send a POST request to the callback_url provided in the initiation request.

Structure

code
integer
Response status code. 0 indicates a successful callback transmission.
msg
string
Response message, usually “ok”.
task_type
string
The type of the task. Enum: image_to_video.
data
object
The payload containing the generation results.

Callback Example

{
    "code": 0,
    "msg": "ok",
    "task_type": "image_to_video",
    "data": {
        "task_id": "i2v-d6b6472bcf724d0399e06d1390cb964e",
        "status": "SUCCEEDED",
        "video_url": "https://storage.googleapis.com/xiling_us_central1_bucket/backend-saas-cdn/image-to-video/9966750584897124421/sample_0.mp4",
        "thumbnail_url": "https://storage.googleapis.com/xiling_us_central1_bucket/backend-saas-cdn/video-ai/tmp/image2video/veo/022934e6-b6d2-4d15-a320-cd60f6e43ae3/i2v-d6b6472bcf724d0399e06d1390cb964e.webp",
        "error_message": ""
    }
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Create an image-to-video generation task. Supports models V, KL, and S.

model
enum<string>
required

Model identifier code.

  • V: Supports single/multi-image, audio, and 4k.
  • KL: Focused on multi-reference image mode.
  • S: Focused on single start-frame mode.
Available options:
V,
KL,
S
Example:

"V"

prompt
string
required

Prompt for video generation. Limit: 1000 characters.

Example:

"A golden retriever running in the grass, sunny day, cinematic lighting"

aspect_ratio
enum<string>
required

Video aspect ratio.

Available options:
16:9,
9:16
Example:

"16:9"

aspect_resolution
enum<string>
required

Video resolution.

  • Model V: 720p, 1080p, 4k
  • Model KL: 720p, 1080p
  • Model S: 720p (fixed)
Available options:
720p,
1080p,
4k
Example:

"1080p"

duration
enum<integer>
required

Video duration in seconds.

  • Model V: 4, 6, 8 (single); 8 (multi)
  • Model KL: 5, 10
  • Model S: 4, 8, 12
Available options:
4,
5,
6,
8,
10,
12
Example:

6

image_url
string<uri>

URL of the start frame image.

  • This field is required for Model S and Model V when using the Start-Frame mode.
  • Not used in Model KL.
  • Limit: Maximum file size is 20MB.
Example:

"https://example.com/start_frame.jpg"

reference_images
string<uri>[]

List of reference image URLs.

  • Required for Model KL and Model V (Multi-image mode).
  • Not used in Model S.
  • Limit: Maximum file size is 20MB.
Example:
[
"https://example.com/ref1.jpg",
"https://example.com/ref2.jpg"
]
generate_audio
boolean
default:false

Whether to generate audio. Only supported by Model V.

Example:

true

generate_count
integer
default:1

Number of videos to generate (1-4).

Required range: 1 <= x <= 4
Example:

1

callback_url
string<uri>

Callback URL for task completion notification.

Example:

"https://your-server.com/callback"

Response

Task created successfully

Task creation response wrapper

code
integer
required

Status code (0 indicates success)

Example:

0

msg
string
required

Response message

Example:

"ok"

data
object
required

Payload containing the generated task IDs