--- title: "kling-v3 Motion JSON Prompt - image2video API Guide" description: "Kling 3.0 motion control on POST /v1/videos/image2video with model_name kling-v3: every field, the motion reference rules, and 3 copy-paste request bodies." canonical: "https://aicontentdrop.com/blog/kling-3-0-motion-json-prompt-guide" source: "https://aicontentdrop.com/blog/kling-3-0-motion-json-prompt-guide" --- Tutorial May 3, 2026 11 min read # Kling 3.0 Motion JSON Prompt — Reference Video API for Newcomers Kling 3.0 motion control on POST /v1/videos/image2video with model_name kling-v3: every field, the motion reference rules, and 3 copy-paste request bodies. json-prompt kling-3-0-motion kling video-to-video ## What This Guide Does This guide explains every field in a Kling 3.0 Motion JSON prompt — the structured request you send to Kuaishou's Kling AI API to generate a video from a still image with precise, controllable movement. By the end you'll be able to send your first Kling 3.0 Motion request and understand exactly what each field in the JSON body does, even if you have never called an AI model API before. We'll start by explaining what Kling 3.0 Motion actually is, then show you a complete request body you can copy and run today. After that we'll break down every field one by one — type, allowed values, default, and a plain-English example of good vs. bad usage. We'll close with three ready-to-use prompt bodies, the curl and JavaScript snippets you need to actually send a request, common error fixes, and a cost breakdown so you know what to budget. No previous coding knowledge required. ## What Is Kling 3.0 Motion? Kling 3.0 Motion is an image-to-video feature built on Kuaishou's Kling 3.0 model. You supply a reference image and a text prompt, then add motion instructions that tell the model *where* things should move and *how* the camera should behave. The result is a short video clip where objects and the camera follow the paths you drew — far more controllable than a plain text-to-video generation. It excels at product shots (a sneaker rotating, liquid pouring, packaging floating into frame) and branded lifestyle footage where you need a specific camera move every time. The one thing it can't do is generate multi-scene narrative or content that has no reference image — for those tasks a pure text-to-video model is the right choice. For a full quality comparison against Veo 3 and SORA 2, see the [Kling vs Veo vs SORA benchmark](https://aicontentdrop.com/blog/kling-veo-sora-benchmark). Kling 3.0 Motion is available via the official Kling AI API at `api.klingai.com`. On AI Content Drop, each Kling 3.0 Motion generation costs **22 credits** — billed only after your video generates successfully. That means if a generation fails you keep your credits (post-deduct billing). To see practical motion-control workflows applied to product ads, check the [Kling 3.0 Motion Control product ads guide](https://aicontentdrop.com/blog/kling-3-0-motion-control-product-ads). ## The Complete kling-v3 Motion-Control JSON Request Body Below is a full Kling 3.0 Motion API request body you can copy, paste, and send right now. This is **JSON** — JavaScript Object Notation, a text format APIs use to send structured requests. Each line is a key–value pair; together they tell Kling exactly what video to generate from your image. ``` { "model_name": "kling-v3", "image": "https://your-cdn.com/product-shot.jpg", "prompt": "The perfume bottle slowly rotates clockwise on a white marble surface, gentle camera push-in from medium to close-up, soft studio lighting with subtle bokeh background", "negative_prompt": "blurry, shaky, watermark, text overlay, distorted reflection", "cfg_scale": 0.5, "mode": "std", "duration": "5", "aspect_ratio": "1:1", "dynamic_masks": [ { "mask": "https://your-cdn.com/bottle-mask.png", "trajectories": [ { "x": 0, "y": 0 }, { "x": 15, "y": 0 }, { "x": 30, "y": 0 }, { "x": 45, "y": 0 }, { "x": 60, "y": 0 } ] } ] } ``` At a glance: `model_name` picks the Kling model version; `image` is the URL of your reference photo; `prompt` describes the motion and style; `cfg_scale` controls how closely the model follows your prompt; `dynamic_masks` is the motion-control layer where you define which pixels move and where they travel. ## Field-by-Field Breakdown Let's go through every field. For each one you'll see its data type, whether it's required, what the default is if you leave it out, and a plain-language example of a good use versus a common mistake. ### model_name **Type:** string (enum) | **Required:** yes Tells the Kling API which model version to run. For Kling 3.0 Motion you use `"kling-v3"`. Older versions (`"kling-v1"`, `"kling-v1-5"`) still work but produce lower-fidelity motion. Always pin a specific version in production so a model upgrade doesn't change your outputs unexpectedly. **Good:** `"kling-v3"` — explicit version, predictable outputs. **Mistake:** Omitting the field entirely. The API requires it; leaving it out returns a missing-field error immediately. ### image **Type:** string (URL) | **Required:** yes A publicly accessible HTTPS URL pointing to the reference image. This is the frame the model animates. Accepted formats are JPEG and PNG. The image must be reachable from Kuaishou's servers — a local file path will not work. If you're testing locally, upload the image to any public storage bucket first and use that URL. **Good:** `"https://your-cdn.com/product-shot.jpg"` — public HTTPS, direct file URL. **Mistake:** A signed URL that expires in 5 minutes. If generation takes longer than that, the API can't fetch the image and the job fails. ### prompt **Type:** string | **Required:** yes A plain-English description of the motion, camera behavior, and visual style you want. The model reads this alongside your `dynamic_masks` trajectories. A good prompt covers three things: what moves (the subject), how the camera behaves (push-in, orbit, static), and the visual feel (soft studio, cinematic, product-ad). Keep it between 20 and 150 words. **Good:** "The bottle gently rotates clockwise while the camera slow-pushes in from medium to close-up, soft studio lighting, clean white backdrop, product advertisement style" **Weak:** "Move the bottle" — too vague; the model will guess direction, speed, and framing, producing an inconsistent result. ### negative_prompt **Type:** string | **Required:** no | **Default:** `""` (empty) A description of things you do *not* want in the output video. Common values for motion-control work: `"blurry, shaky camera, watermark, distorted object, text overlay"`. Keep it under 80 words and be specific — vague negatives like "bad quality" have no measurable effect. **Good:** `"blurry, shaky, duplicate objects, watermark"` **Mistake:** `"no ugly video"` — the model has no way to interpret what "ugly" means for your specific subject. ### cfg_scale **Type:** number (float) | **Required:** no | **Default:** `0.5` | **Range:** 0.0 – 1.0 **cfg_scale** (classifier-free guidance scale) controls how strictly the model follows your text prompt versus doing its own thing. A value of `0.5` is a balanced middle ground. Higher values (0.7–1.0) make the model stick very closely to your description but can produce stiffer, less natural motion. Lower values (0.2–0.4) give the model more creative freedom but the output may drift from your prompt. **Good:** `0.5` for most ad work — natural motion that still matches the prompt. **Mistake:** Setting `1.0` for every job — over-guidance often produces jerky or artificial-looking movement in motion-control outputs. ### mode **Type:** string (enum) | **Required:** no | **Default:** `"std"` | **Allowed values:** `"std"`, `"pro"` Selects the quality/speed tier. `"std"` (standard) is faster and uses less processing time. `"pro"` produces higher-fidelity output — sharper textures, more consistent object edges, smoother motion paths — but takes longer and may cost more API quota. Use `"std"` while iterating on a prompt, then switch to `"pro"` for the final creative you plan to publish. Consult the latest Kling docs at [klingai.com/dev](https://docs.qingque.cn/d/home/eZQAtsrntpINKohS3mJ_LiDxc) to confirm current mode behavior. **Good:** `"std"` for testing 10 prompt variations; `"pro"` for the 2 winning variants. **Mistake:** Always using `"pro"` during creative development — you burn generation quota on prompts you'll discard anyway. ### duration **Type:** string (enum) | **Required:** no | **Default:** `"5"` | **Allowed values:** `"5"`, `"10"` How long the generated video clip should be, in seconds. Note that this is sent as a string (`"5"`), not a number. Most single-product ad shots work well at 5 seconds — it's enough for a full rotation or push-in. Use `"10"` when you need a slower, more cinematic movement or want to show multiple angles in one clip. **Good:** `"5"` for a product rotation hook in a Meta ad. **Mistake:** Sending the integer `5` instead of the string `"5"` — the API expects a string and may reject or misinterpret a bare number. ### aspect_ratio **Type:** string (enum) | **Required:** no | **Default:** `"16:9"` | **Allowed values:** see reference table below Sets the width-to-height proportion of the output video. Match this to your reference image's composition and your intended platform. `"9:16"` is vertical (TikTok, Instagram Reels), `"16:9"` is landscape (YouTube, display ads), and `"1:1"` is square (Instagram feed, some Facebook placements). **Good:** `"1:1"` when your reference image is a square product photo. **Mistake:** Sending a ratio that doesn't match your image — the model will pad or crop the reference, and motion trajectories drawn for the original frame will point to the wrong places. ### dynamic_masks **Type:** array of objects | **Required:** no (but this is the whole point of Motion) This is the heart of Kling Motion. Each object in the array defines one moving region: a `mask` (a PNG image where white pixels mark the object to move) and a `trajectories` array (a list of `{ x, y }` coordinate points that describe the path the masked region should travel over the clip duration). You can include multiple mask objects to move multiple elements independently — for example, a product and a shadow as separate regions. If you omit this field entirely the generation falls back to standard image-to-video behaviour without controlled motion. **Good:** One mask per distinct moving element. Trajectories with 5 points spaced evenly for a 5-second clip. **Mistake:** Giving 20 closely spaced trajectory points that all point in the same direction — the model interprets dense identical points as "stay still" rather than "move at constant speed". ### static_mask **Type:** string (URL) | **Required:** no | **Default:** none An optional PNG mask URL where white pixels mark regions that should *not* move at all. This is useful when your reference image has a background element — like a branded backdrop or a logo card — that must stay locked in place while everything else animates. Consult the latest Kling docs to confirm exact field behavior for your model version. **Good:** Pass a mask that covers your brand logo when the product in the foreground is rotating. **Mistake:** Using the same PNG for both `dynamic_masks` and `static_mask` — the two masks describe opposite intents and will conflict. ## Allowed Values Reference Table Bookmark this table. When you get an "invalid parameter" error, check here first. | Field | Allowed values | Notes | | --- | --- | --- | | `model_name` | `"kling-v1"`, `"kling-v1-5"`, `"kling-v3"` | Use `"kling-v3"` for Kling 3.0 Motion. | | `mode` | `"std"`, `"pro"` | Default `"std"`. Pro is higher fidelity, slower. | | `duration` | `"5"`, `"10"` | Seconds, sent as a string. Default `"5"`. | | `aspect_ratio` | `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"`, `"21:9"`, `"9:21"` | Default `"16:9"`. Consult latest Kling docs to confirm all available ratios for your model version. | | `cfg_scale` | 0.0 – 1.0 (float) | Default 0.5. Higher = follows prompt more strictly. | | `prompt` | Any string, up to ~2500 chars | Required. Sweet spot 20–150 words. | | `negative_prompt` | Any string | Optional. Keep under 80 words, be specific. | | `dynamic_masks[n].trajectories` | Array of `{ x: number, y: number }` | Pixel offsets from mask center. Recommend 4–8 points per 5 s. | ## 3 Working Copy-Paste Examples ### Example 1: E-commerce — Rotating Skincare Product ``` { "model_name": "kling-v3", "image": "https://your-cdn.com/serum-bottle-white-bg.jpg", "prompt": "The serum bottle rotates slowly clockwise on a glossy white pedestal, camera stays static in a medium close-up, soft even studio lighting, luxury skincare advertisement aesthetic", "negative_prompt": "blurry, shaky, shadows too harsh, watermark, text, duplicate bottle", "cfg_scale": 0.5, "mode": "pro", "duration": "5", "aspect_ratio": "1:1", "dynamic_masks": [ { "mask": "https://your-cdn.com/bottle-silhouette-mask.png", "trajectories": [ { "x": 0, "y": 0 }, { "x": 8, "y": 0 }, { "x": 16, "y": 0 }, { "x": 24, "y": 0 }, { "x": 32, "y": 0 } ] } ] } ``` The square ratio matches most product photography crops and works well for Instagram feed and Amazon listing thumbnails. The `pro` mode ensures the glass texture of the serum bottle reads cleanly. The trajectory points move the bottle mask slightly to the right over 5 seconds — combined with the rotation prompt, the model interprets this as a rotating object. Expect a clean, premium-feel loop suitable for a skincare brand paid media campaign. The `static_mask` field was omitted here because the background is plain white and needs no protection. ### Example 2: Portrait — Confident Founder Talking-Head ``` { "model_name": "kling-v3", "image": "https://your-cdn.com/founder-studio-portrait.jpg", "prompt": "The founder gestures naturally while speaking to camera, slow subtle push-in from medium shot to medium close-up, soft window light from the left, natural and warm UGC-style testimonial feel", "negative_prompt": "distorted face, extra hands, blurry, watermark, stiff robotic motion", "cfg_scale": 0.45, "mode": "std", "duration": "5", "aspect_ratio": "9:16", "dynamic_masks": [ { "mask": "https://your-cdn.com/person-mask.png", "trajectories": [ { "x": 0, "y": 0 }, { "x": -3, "y": -2 }, { "x": -6, "y": -4 }, { "x": -9, "y": -6 }, { "x": -12, "y": -8 } ] } ] } ``` Vertical ratio (9:16) places the founder front and centre for TikTok or Reels placement. Lowering `cfg_scale` to 0.45 gives the model slightly more latitude on natural gesture variation — useful for human subjects where rigid prompt adherence can make body language look robotic. The trajectory nudges the person mask slightly up and left, reinforcing the push-in described in the prompt. Using `std` mode is appropriate here because the intentional imperfection of UGC style means hyper-sharp rendering would look out of place. ### Example 3: Cinematic — Floating Product Hero Shot ``` { "model_name": "kling-v3", "image": "https://your-cdn.com/sneaker-dark-studio.jpg", "prompt": "The sneaker floats upward slowly against a deep black background with faint particle dust, very slow camera pull-back from close-up to medium shot, rim-lit product with dramatic side shadow, cinematic luxury advertisement", "negative_prompt": "blurry edges, motion blur on logo, background objects, watermark", "cfg_scale": 0.6, "mode": "pro", "duration": "10", "aspect_ratio": "16:9", "dynamic_masks": [ { "mask": "https://your-cdn.com/sneaker-mask.png", "trajectories": [ { "x": 0, "y": 0 }, { "x": 0, "y": -10 }, { "x": 0, "y": -20 }, { "x": 0, "y": -30 }, { "x": 0, "y": -40 }, { "x": 0, "y": -50 } ] } ], "static_mask": "https://your-cdn.com/brand-logo-area-mask.png" } ``` The 10-second duration lets the floating motion complete slowly and elegantly — rushed at 5 seconds, the effect would look unnatural. The trajectory moves the sneaker mask straight upward (negative Y values) over the full clip duration. A `static_mask` locks the brand logo watermark in the corner so it doesn't drift with the product. Setting `cfg_scale` to 0.6 keeps the cinematic mood of the prompt visible in the output without making the movement stiff. Landscape ratio suits the wide hero composition typical of premium display and pre-roll ad placements. ## POST /v1/videos/image2video — How to Send the Request An **API endpoint** is a URL your code sends a request to — think of it as the address where the Kling AI service lives. The official Kling AI API endpoint for image-to-video (which is what Motion uses) is `https://api.klingai.com/v1/videos/image2video`. You send an HTTP POST request with your JSON body to that URL. Authentication uses a **JWT token** (JSON Web Token) that you sign yourself from your Kling API key and API secret — both available from the Kuaishou developer dashboard. The exact JWT signing process is documented at [klingai.com/dev](https://docs.qingque.cn/d/home/eZQAtsrntpINKohS3mJ_LiDxc); consult the latest docs there for the current signing algorithm and header format. Here is a curl example (run this in your terminal): ``` curl -X POST https://api.klingai.com/v1/videos/image2video \ -H "Authorization: Bearer YOUR_KLING_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model_name": "kling-v3", "image": "https://your-cdn.com/product-shot.jpg", "prompt": "The bottle rotates slowly, soft studio lighting, luxury product ad", "cfg_scale": 0.5, "mode": "std", "duration": "5", "aspect_ratio": "1:1" }' ``` Here is the same request in JavaScript (works in Node.js or a browser): ``` const response = await fetch("https://api.klingai.com/v1/videos/image2video", { method: "POST", headers: { "Authorization": "Bearer YOUR_KLING_JWT_TOKEN", "Content-Type": "application/json" }, body: JSON.stringify({ model_name: "kling-v3", image: "https://your-cdn.com/product-shot.jpg", prompt: "The bottle rotates slowly, soft studio lighting, luxury product ad", cfg_scale: 0.5, mode: "std", duration: "5", aspect_ratio: "1:1" }) }); const data = await response.json(); console.log(data.data?.task_id); // save this for polling ``` Or skip the API key entirely — paste your prompt into the [Chat-to-Ads Studio](https://aicontentdrop.com/) or the [video generation page](https://aicontentdrop.com/best-ai-video-generator) and we'll handle the request for you. ## What the Response Looks Like Kling 3.0 Motion is an **async** model — it does not return the finished video immediately. When you POST your request, you get a task ID back right away. You then **poll** a separate status endpoint every few seconds until the task state changes to complete. Initial response right after you POST: ``` { "code": 0, "message": "success", "request_id": "req_abc123xyz", "data": { "task_id": "task_7f3a2b1c9d4e", "task_status": "submitted" } } ``` Save the `task_id`. Then poll the status endpoint. Consult the latest Kling docs at klingai.com/dev for the exact status endpoint path — it follows the pattern `GET https://api.klingai.com/v1/videos/image2video/{task_id}`. When the video is ready, the response looks like this: ``` { "code": 0, "message": "success", "request_id": "req_abc123xyz", "data": { "task_id": "task_7f3a2b1c9d4e", "task_status": "succeed", "task_result": { "videos": [ { "id": "vid_001", "url": "https://cdn.klingai.com/results/task_7f3a2b1c9d4e/output.mp4", "duration": "5" } ] } } } ``` The `task_status` field moves through: `submitted` → `processing` → `succeed` (or `failed` if something went wrong). When status is `succeed`, the `task_result.videos[0].url` field holds the direct download URL for your video. Most Kling 3.0 Motion generations complete in 60–120 seconds. Poll no faster than every 5 seconds to avoid hitting rate limits. ## Common Errors and Fixes - Error: invalid_aspect_ratio or "aspect_ratio not supported" Meaning: You passed a ratio Kling does not accept for this model version (e.g., "4:5" ). Fix: Use one of the ratios in the reference table above. For portrait ads, use "9:16" and crop to 4:5 in your video editor if needed. - Error: 401 Unauthorized Meaning: Your JWT token is missing, expired, or incorrectly signed. Fix: Regenerate a fresh JWT from your API key and secret following the signing instructions in the Kling developer docs. JWTs typically expire after a short window — generate one per request or cache with a short TTL. - Error: image_fetch_failed or a 4xx on the image URL Meaning: Kuaishou's servers could not download your reference image at the URL you provided. Fix: Make sure the image is at a public HTTPS URL with no authentication required. Test by opening the URL in an incognito browser tab — if you need to log in, the API will fail too. - Error: prompt_too_long or 422 Unprocessable Entity with a prompt-length message Meaning: Your prompt or negative prompt exceeds the character limit. Fix: Trim your prompt. Focus on one motion, one camera move, and one style phrase. Everything else is noise. - Error: content_policy_violation Meaning: Your prompt triggered Kuaishou's safety filter — usually references to real named individuals, graphic violence, or explicit content. Fix: Replace specific names with descriptions ("a tech founder" instead of a real person's name). Remove graphic language. - Error: 429 Too Many Requests Meaning: You've hit the API rate limit or your credit balance is zero. Fix: Wait before retrying. If credits are the issue, top up your account. On AI Content Drop, each Kling 3.0 Motion generation costs 22 credits. You are not charged for failed generations (post-deduct billing). - Error: task_status: "failed" in the polling response Meaning: The model attempted generation but could not complete it — usually a transient server-side issue. Fix: Retry the same request with a different cfg_scale value (try 0.4 or 0.6). If it fails three times, check the Kling API status page. You are not charged for failed generations on AI Content Drop. ## Kling 3.0 Motion vs Alternatives — When to Use Which Not every video job needs motion control. Here's a plain comparison to help you pick the right model for your creative. You can browse all available models on the [model marketplace](https://aicontentdrop.com/marketplace). | Use this if… | Model | Credits | | --- | --- | --- | | You have a reference image and need a specific, repeatable camera move or object trajectory — product rotations, floating hero shots, controlled push-ins. Read the full model breakdown in the [Kling 3.0 review](https://aicontentdrop.com/blog/kling-3-0-review). | Kling 3.0 Motion | 22 | | You want high-realism footage from a text description only — talking heads, lifestyle scenes, UGC-style content — and don't have a reference image | Kling 3.0 | 22 | | You need physics-accurate fluid motion, multi-character scenes, or cinematic quality that outpaces Kling at higher compute cost — see the [three-model benchmark](https://aicontentdrop.com/blog/kling-veo-sora-benchmark) for head-to-head results | Veo 3.1 | 26 | ## Cost Math for Newcomers Let's work through a real budget example so you know what to expect. Say you want to produce **10 motion-controlled product ad variants** for a launch campaign — different camera angles, different motion paths, different prompts. Each Kling 3.0 Motion generation costs **22 credits**. Ten variants = 220 credits. On the Starter plan ($19/month, 150 credits), that single batch of 10 would exceed your monthly allocation by 70 credits — so either add a credit top-up or move to a higher plan. On the Professional plan ($49/month, 450 credits), you can run roughly 20 full 10-variant campaigns per month with credits to spare. The key thing to remember: you are only charged on successful generations (post-deduct billing). A failed generation returns the credits to your balance. To minimize waste during development: use `mode: "std"` for exploratory prompt variations, and only switch to `mode: "pro"` for the 2–3 variants you plan to publish. That alone can cut your effective per-campaign credit spend by 20–30%. ## Glossary **Prompt** The text description you write to tell the AI model what motion and style to generate. Goes in the `prompt` field of your JSON request. **JSON (JavaScript Object Notation)** A plain-text format for sending structured data to APIs. Uses curly braces `{}`, key–value pairs separated by colons, and commas between pairs. **API request** A message your code sends to a remote service — like the Kling AI API — asking it to do something. The request includes a URL, a method (POST or GET), and usually a JSON body. **Endpoint** The specific URL you POST your request to. For Kling 3.0 Motion the endpoint is `https://api.klingai.com/v1/videos/image2video`. **JWT (JSON Web Token)** A short signed string that proves your identity to the Kling API. You generate it from your API key and API secret using the Kling signing algorithm described in their developer docs. **task_id** A unique identifier the API returns when you submit a generation job. You use it to poll the status endpoint and eventually retrieve your video URL. **Polling** The process of repeatedly asking the API "is the video ready yet?" by making GET requests to the status endpoint every few seconds until the task state changes to `succeed`. **dynamic_masks** The motion-control field in a Kling Motion request. You supply a mask image (which pixels to move) and trajectory coordinates (where to move them). **cfg_scale** Classifier-free guidance scale — a number from 0 to 1 that controls how strictly the model follows your text prompt. Higher = more literal; lower = more creative freedom. ## FAQ ### Can I just use the chat instead of writing JSON? Yes. The [Chat-to-Ads Studio](https://aicontentdrop.com/) lets you describe your video in plain English and handles all the JSON formatting and API calls for you. Writing raw JSON gives you more precise control over trajectory coordinates and masking — but for most newcomers, starting with the chat interface is faster and far less error-prone. ### What if I get a 401 error? A 401 means your JWT token is missing, expired, or was signed with the wrong key or algorithm. Regenerate a fresh token directly from your Kling developer dashboard credentials, following the JWT signing guide in the official Kling docs. Tokens are time-limited — generate a new one for each request, or cache with a TTL shorter than the expiry window. ### How do I get an aspect ratio not in the list? You can't — Kling only generates at the ratios listed in the reference table above. If you need a different ratio (like 4:5 for an Instagram portrait ad), generate at `9:16` and crop the top and bottom in a video editor afterward. Most editing tools let you do this in under a minute with no quality loss. ### Does Kling 3.0 Motion work without a reference image? No. Motion is an image-to-video feature — it requires a reference image to animate. If you want to generate video from a text description only, use the standard Kling 3.0 text-to-video mode on the [video generation page](https://aicontentdrop.com/best-ai-video-generator) instead. Both cost 22 credits per generation.