Image to Video

Create a Kling-compatible image-to-video task.

Create Task

Request

POST /v1/videos/image2video

Field	Type	Required	Supported values and limits	Description
model_name	string	Yes	kling-v2-5-turbo, kling-v3	Model name. kling-v2-5-turbo is suited for basic image-to-video, while kling-v3 supports multi-shot generation, reference elements, and longer durations.
image	string	Yes	Public URL or raw Base64	First-frame reference image. Supports .jpg, .jpeg, and .png, with a maximum size of 10MB, minimum side length of 300px, and an aspect ratio between 1:2.5 and 2.5:1. If you use Base64, pass only the raw content without the data:image/...;base64, prefix.
image_tail	string	No	Public URL or raw Base64	End-frame reference image. Supports .jpg, .jpeg, and .png, with a maximum size of 10MB and minimum side length of 300px; there is no aspect ratio restriction. Do not provide an end frame without a first frame. Under kling-v2-5-turbo, using both first and end frame together is supported only when mode=pro.
prompt	string	No	Up to 2500 chars	Under kling-v3, it is required when multi_shot=false and is used to describe how the video should evolve from the first frame, including action and camera behavior; when multi_shot=true, this field is ignored. Under kling-v2-5-turbo, it is optional.
multi_shot	boolean	No	Only kling-v3; true, false	Enables multi-shot generation. Default is false. When multi_shot=true, prompt is ignored; when multi_shot=false, shot_type and multi_prompt are ignored. kling-v2-5-turbo does not support this field.
shot_type	string	No	Only kling-v3; only customize is supported	Required when multi_shot=true; ignored when multi_shot=false. Only custom storyboards are supported. intelligence is not supported.
multi_prompt	array	No	Only kling-v3; 1 to 6 items	Required when multi_shot=true and shot_type=customize; ignored when multi_shot=false. Used to define prompt and duration for each shot.
multi_prompt[].index	integer	Yes	Only kling-v3	Shot index. Using 1,2,3... in order is recommended.
multi_prompt[].prompt	string	Yes	Only kling-v3; up to 512 chars	Prompt for the current shot.
multi_prompt[].duration	string	Yes	Only kling-v3; at least 1 second	Duration of the current shot. The sum of all shot durations must equal the total duration.
negative_prompt	string	No	Up to 2500 chars	Negative prompt used to restrict unwanted content or effects.
element_list	array	No	Only kling-v3	Reference element list. Up to 3 elements are supported. kling-v2-5-turbo does not support this field.
element_list[].element_id	integer	Yes	Only kling-v3	Element ID from the element library.
sound	string	No	Only kling-v3; on, off	Whether to generate audio together with the video. Default is off. kling-v2-5-turbo does not support this field.
mode	string	No	std, pro	Generation mode. std is the standard mode. pro is the higher-quality mode. 4k is not supported.
aspect_ratio	string	No	16:9, 9:16, 1:1	If provided, only these three values are supported.
duration	string	No	kling-v2-5-turbo: 5, 10; kling-v3: 3 to 15	Total video duration in seconds.
watermark_info	object	No	{"enabled": boolean}	Whether to return a watermarked result in parallel.
external_task_id	string	No	Custom string	Custom task ID for later query use. It must be unique within the same account.

Response

{
  "code": 0,
  "message": "success",
  "request_id": "req_abc123",
  "data": {
    "task_id": "sg_vid_xxxxxxxx",
    "task_status": "submitted",
    "created_at": 1776209922,
    "updated_at": 1776209922
  }
}

Example

Basic Example

curl -sS "https://api.exchangetoken.ai/v1/videos/image2video" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image": "https://example.com/first-frame.png",
    "prompt": "The person turns toward the camera and smiles, gentle handheld camera movement",
    "mode": "std",
    "sound": "off",
    "duration": "5",
    "watermark_info": {"enabled": false}
  }'

First and End Frame Example

curl -sS "https://api.exchangetoken.ai/v1/videos/image2video" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image": "https://example.com/first-frame.png",
    "image_tail": "https://example.com/end-frame.png",
    "prompt": "Smoothly transform the first frame into the final frame",
    "mode": "pro",
    "sound": "off",
    "duration": "5"
  }'

Query Task

Request

GET /v1/videos/image2video/{task_id}

Use data.task_id for polling.

Response

{
  "code": 0,
  "message": "success",
  "request_id": "req_abc123",
  "data": {
    "task_id": "sg_vid_xxxxxxxx",
    "task_status": "succeed",
    "watermark_info": {
      "enabled": false
    },
    "task_result": {
      "videos": [
        {
          "url": "https://example.com/output.mp4"
        }
      ]
    },
    "created_at": 1776209922,
    "updated_at": 1776210072
  }
}

Status Values

task_status	Meaning
submitted	Task accepted but not yet running.
processing	Task is queued or running.
succeed	Task completed and task_result.videos may be present.
failed	Task failed or was cancelled. Check task_status_msg when present.

Example

curl -sS "https://api.exchangetoken.ai/v1/videos/image2video/sg_vid_xxxxxxxx" \
  -H "Authorization: Bearer sk-xxxxxx"