> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keevx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiate an image-to-video generation task
> Create a task to generate video from images using models V, KL, or S.
### 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 Video
**Features**: 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 Video
**Features**: 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 Model
**Features**: 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
Response status code. `0` indicates a successful callback transmission.
Response message, usually "ok".
The type of the task. Enum: `image_to_video`.
The payload containing the generation results.
The unique identifier for the video generation task.
The execution status of the task. Enum: `SUCCEEDED`, `FAILED`.
The URL to access/download the generated video (valid when status is SUCCEEDED).
The URL of the generated video's thumbnail/cover image.
Detailed error information if the task status is FAILED.
### Callback Example
```json theme={null}
{
"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": ""
}
}
```
## OpenAPI
````yaml POST /v1/image_to_video
openapi: 3.1.1
info:
title: OpenAPI Plant Store
description: >-
A sample API that uses a plant store as an example to demonstrate features
in the OpenAPI specification
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.keevx.com/
security:
- bearerAuth: []
paths:
/v1/image_to_video:
post:
summary: Create Image to Video Task
description: Create a task to generate video from images using models V, KL, or S.
operationId: createImageToVideoTask
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ImageToVideoRequest'
responses:
'200':
description: Task created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreatedResponse'
'400':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
ImageToVideoRequest:
type: object
description: Create an image-to-video generation task. Supports models V, KL, and S.
required:
- model
- prompt
- aspect_ratio
- aspect_resolution
- duration
properties:
model:
type: string
description: |-
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.
enum:
- V
- KL
- S
example: V
prompt:
type: string
description: 'Prompt for video generation. Limit: 1000 characters.'
example: >-
A golden retriever running in the grass, sunny day, cinematic
lighting
image_url:
type: string
format: uri
description: >-
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:
type: array
description: |-
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.
items:
type: string
format: uri
example:
- https://example.com/ref1.jpg
- https://example.com/ref2.jpg
aspect_ratio:
type: string
description: Video aspect ratio.
enum:
- '16:9'
- '9:16'
example: '16:9'
aspect_resolution:
type: string
description: |-
Video resolution.
* Model V: 720p, 1080p, 4k
* Model KL: 720p, 1080p
* Model S: 720p (fixed)
enum:
- 720p
- 1080p
- 4k
example: 1080p
duration:
type: integer
description: |-
Video duration in seconds.
* Model V: 4, 6, 8 (single); 8 (multi)
* Model KL: 5, 10
* Model S: 4, 8, 12
enum:
- 4
- 5
- 6
- 8
- 10
- 12
example: 6
generate_audio:
type: boolean
description: Whether to generate audio. Only supported by Model V.
default: false
example: true
generate_count:
type: integer
description: Number of videos to generate (1-4).
default: 1
minimum: 1
maximum: 4
example: 1
callback_url:
type: string
format: uri
description: Callback URL for task completion notification.
example: https://your-server.com/callback
TaskCreatedResponse:
type: object
description: Task creation response wrapper
properties:
code:
type: integer
description: Status code (0 indicates success)
example: 0
msg:
type: string
description: Response message
example: ok
data:
type: object
description: Payload containing the generated task IDs
properties:
task_ids:
type: array
description: List of generated task IDs used to query status
items:
type: string
description: Unique Task ID
example: i2v-d6b6472bcf724d0399e06d1390cb964e
example:
- i2v-d6b6472bcf724d0399e06d1390cb964e
- i2v-fc654817587e435e937f1e1b80366c00
required:
- task_ids
required:
- code
- msg
- data
Error:
required:
- code
- msg
type: object
properties:
code:
type: integer
format: int32
example: 100001
msg:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````