Initiate an image-to-video generation task

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

POST

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:

Model V
Model KL
Model S

Name: Standard Model-Start & End Frame VideoFeatures: Supports audio, multiple resolutions, and three image input modes.

Parameter	Required	Description
prompt	Yes	Limited to 1000 characters.
image_url	No	Required for Start-Frame Mode.
end_image_url	No	Supports end frame upload.
reference_images	No	Required for Multi-Image Mode. (Max 3 images)
aspect_resolution	Yes	Supports `720p`, `1080p`, `4k`.
duration	Yes	Single-image: `4`, `6`, `8`s; Multi-image: fixed at `8`s.
generate_audio	No	Supports audio configuration.

Name: Standard Model-Multi-Reference to VideoFeatures: Enforces multi-reference image input.

Parameter	Required	Description
prompt	Yes	Image-to-video prompt.
reference_images	Yes	Must provide a list of reference images. (Max 7 images)
aspect_resolution	Yes	Supports `720p`, `1080p`.
duration	Yes	Supports `5`, `10`s.
image_url	No	Not supported.

Name: Pro ModelFeatures: Enforces single start-frame image input.

Parameter	Required	Description
prompt	Yes	Limited to 1000 characters.
image_url	Yes	Must provide the start frame URL.
aspect_resolution	Yes	Fixed at `720p`.
duration	Yes	Supports `4`, `8`, `12`s.
reference_images	No	Not supported.

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

integer

Response status code. 0 indicates a successful callback transmission.

string

Response message, usually “ok”.

string

The type of the task. Enum: image_to_video.

object

The payload containing the generation results.

Show Show properties

string

The unique identifier for the video generation task.

string

The execution status of the task. Enum: SUCCEEDED, FAILED.

string

The URL to access/download the generated video (valid when status is SUCCEEDED).

string

The URL of the generated video’s thumbnail/cover image.

string

Detailed error information if the task status is FAILED.

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

Show child attributes

API documentation

Image to video

Video translate

Image generate

Initiate an image-to-video generation task

Detailed Model Parameter Rules

end_image_url bad case Notes

Callback Notification

Structure

Callback Example

Authorizations

Body

Response

​Detailed Model Parameter Rules

​end_image_url bad case Notes

​Callback Notification

​Structure

​Callback Example

Authorizations

Body

Response

Detailed Model Parameter Rules

end_image_url bad case Notes

Callback Notification

Structure

Callback Example