Kling v3 Video Generation

• Async processing mode, returns task ID for subsequent queries
• Supports text-to-video, image-to-video (first frame/first-last frame control)
• Supports standard mode (720P), professional mode (1080P), and 4K mode
• Text-to-video supports 15-second duration
• Supports generating videos with audio

POST /v1/videos/generations

cURL

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "kling-v3",
    "prompt": "A golden cat running on a sunlit meadow, slow motion, cinematic quality",
    "mode": "std",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

200

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_xxxxxxxxxx"
    }
  ]
}

cURL

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "kling-v3",
    "prompt": "A golden cat running on a sunlit meadow, slow motion, cinematic quality",
    "mode": "std",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

200

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_xxxxxxxxxx"
    }
  ]
}

Authorization

Authorization · string · required

All API endpoints require Bearer Token authentication

Get your API Key:

Visit the API Key Management Page to get your API Key

Add it to the request header:

Authorization: Bearer YOUR_API_KEY

Request Parameters

model · string · required

Video generation model name

Supported models:

• kling-v3 - Kling v3 (recommended)

prompt · string · required

Text prompt

Describe scenes, actions, styles in detail for better generation results. English prompts are recommended.

Example: "a golden retriever running on the beach, sunset, cinematic"

mode · string · default: "std"

Generation mode

Options:

• std - Standard mode (720P)
• pro - Professional mode (1080P)
• 4k - 4K mode

Default: std

duration · integer · default: "5"

Default: 5 Video duration (seconds)

Range: 3-15 (minimum 3 seconds, maximum 15 seconds)

⚠️ Note: Must be a plain number (e.g. 6), do not add quotes, otherwise an error will occur

aspect_ratio · string · default: "16:9"

Video aspect ratio

Options:

• 16:9 - Landscape
• 9:16 - Portrait
• 1:1 - Square

Default: 16:9

negative_prompt · string

Negative prompt to exclude unwanted content

Example: "blurry, low quality, distorted"

image_urls · array<url>

Image URL array for image-to-video generation

• Pass 1 image: used as first frame
• Pass 2 images: automatically assigned as first frame + last frame

Maximum 2 images supported

Example: ["https://example.com/first.jpg"]

• Maximum 2 images supported
• Image URLs must be publicly accessible without hotlink protection
• In image-to-video mode, aspect_ratio may be overridden by the actual image ratio

watermark · boolean

Whether to add watermark

audio · boolean · default: "false"

Whether to generate video with audio

multi_shot · boolean · default: "false"

Whether to enable multi-shot mode.

• true
• false

shot_type · string

Shot split method: customize / intelligence.

Required when multi_shot=true.

multi_prompt · array<object>

Per-shot information, such as prompt and duration.

Define shot order, prompt, and duration via index, prompt, and duration.

• Supports 1 to 6 shots
• Maximum content length per shot is 512
• Each shot duration must be >= 1 and cannot exceed total task duration
• Sum of all shot durations must equal top-level duration

Format:

"multi_prompt": [
  { "index": 1, "prompt": "string", "duration": 5 },
  { "index": 2, "prompt": "string", "duration": 5 }
]

Required when multi_shot=true and shot_type=customize.

element_list · array<object>

Reference subject list, up to 3 subjects.

• Create on the fly via name, description, element_input_urls

Example:

[
  {
    "name": "element_dog",
    "description": "a golden retriever, fluffy fur, friendly expression",
    "element_input_urls": [
      "https://example.com/image1.png",
      "https://example.com/image2.png"
    ]
  },
  {
    "name": "element_cat",
    "description": "an orange tabby cat, round face, bright eyes",
    "element_input_urls": [
      "https://example.com/image1.png",
      "https://example.com/image2.png"
    ]
  }
]

Notes:

• name, description, and element_input_urls are required for on-the-fly creation
• element_input_urls: 2-4 images per subject (first as frontal image, rest as references)
• Reference elements in prompt with @name, e.g. "@element_dog chasing @element_cat on grass"

Parameter Constraints

• mode=4k is supported for kling-v3
• image_urls supports up to 2 images (1 first frame, 2 first+last frames)
• Last-frame-only input is invalid (must include first frame)
• When multi_shot=true, top-level prompt can be omitted
• multi_prompt supports up to 6 shots, and index must start from 1 and be continuous

Feature Support Matrix

Type	Feature	std 5s	std 10s	std 15s	pro 5s	pro 10s
Text-to-Video	Generation	✅	✅	✅	✅	✅
Image-to-Video	Generation	✅	✅	✅	✅	✅
Image-to-Video	First Frame	✅	✅	✅	✅	✅
Image-to-Video	Last Frame	✅	✅	✅	✅	✅

Text-to-Video vs Image-to-Video

The system automatically determines the mode based on whether image_urls is provided: no images means text-to-video, with images means image-to-video.

Parameter	Text-to-Video	Image-to-Video
prompt	✅ Required	✅ Required
image_urls	❌ Not used	✅ Required (1-2 images)
negative_prompt	✅ Optional	✅ Optional
mode	✅ Optional	✅ Optional
duration	✅ Optional (3-15)	✅ Optional (3-15)
aspect_ratio	✅ Optional	⚠️ May be overridden by image ratio
watermark	✅ Optional	✅ Optional
audio	✅ Optional	✅ Optional

Response

code · integer

Response status code, 200 on success

data · array

Response data array

Show Array Elements

status · string

Task status, submitted when initially submitted

task_id · string

Unique task identifier for querying task status and results

Use Cases

Case 1: Text-to-Video (Standard Mode)

{
  "model": "kling-v3",
  "prompt": "A golden cat running on a sunlit meadow, slow motion, cinematic quality",
  "mode": "std",
  "duration": 5,
  "aspect_ratio": "16:9"
}

Case 2: Text-to-Video (Pro Mode + Negative Prompt)

{
  "model": "kling-v3",
  "prompt": "Tokyo Shibuya crossing at night, neon lights reflected on wet ground, people walking with umbrellas",
  "negative_prompt": "blurry, low quality, distorted",
  "mode": "pro",
  "duration": 10,
  "aspect_ratio": "16:9"
}

Case 3: Text-to-Video (15 seconds)

{
  "model": "kling-v3",
  "prompt": "a time-lapse of a flower blooming in a garden",
  "duration": 15,
  "aspect_ratio": "16:9"
}

Case 4: Image-to-Video (First Frame)

{
  "model": "kling-v3",
  "prompt": "the cat slowly walks forward and looks around",
  "image_urls": ["https://example.com/cat.jpg"],
  "mode": "std",
  "duration": 5
}

Case 5: Image-to-Video (First + Last Frame Control)

{
  "model": "kling-v3",
  "prompt": "smooth cinematic transition",
  "image_urls": [
    "https://example.com/frame-start.jpg",
    "https://example.com/frame-end.jpg"
  ],
  "mode": "std",
  "duration": 5
}

Case 6: Generate Video with Audio

{
  "model": "kling-v3",
  "prompt": "A rock singer singing on this stage, concert scene, flashing lights",
  "audio": true,
  "mode": "std",
  "duration": 5
}

Case 7: Multi-Shot Storyboard (customize, 15 seconds, portrait with audio)

{
  "model": "kling-v3",
  "multi_prompt": [
    {
      "index": 1,
      "prompt": "Two friends talking under a streetlight at night. Warm glow, casual poses, no dialogue.",
      "duration": 2
    },
    {
      "index": 2,
      "prompt": "A runner sprinting through a forest, leaves flying. Low-angle shot, focus on movement.",
      "duration": 3
    },
    {
      "index": 3,
      "prompt": "A woman hugging a cat, smiling. Soft sunlight, cozy home setting, emphasize warmth.",
      "duration": 3
    },
    {
      "index": 4,
      "prompt": "A door creaking open, shadowy hallway. Dark tones, minimal details, eerie mood.",
      "duration": 3
    },
    {
      "index": 5,
      "prompt": "A man slipping on a banana peel, shocked expression. Exaggerated pose, bright colors.",
      "duration": 3
    },
    {
      "index": 6,
      "prompt": "A sunset over mountains, small figure walking away. Wide angle, peaceful atmosphere.",
      "duration": 1
    }
  ],
  "multi_shot": true,
  "shot_type": "customize",
  "duration": 15,
  "mode": "pro",
  "audio": true,
  "size": "9:16"
}

Query Task Results

Video generation is an async task that returns a task_id upon submission. Use the Get Task Status endpoint to query generation progress and results.