Video modelsAdvanced usersUpdated
POST/v1/videos/generations

API console

POST/v1/videos/generations
View keys

Requests use the API key you enter and follow standard API billing.

Kling V3 Motion Control

Request ID kling-v3-motion-control

Protocols

Authentication

Requests require an API key from API key management. For JSON requests, set Content-Type: application/json.

  • Authorization: Bearer YOUR_API_KEY

Request parameters

POST /v1/videos/generations

FieldTypeRequiredDescription
modelstringRequiredkling-v3-motion-control. Use the model ID shown on this page.
promptstringOptionalOptionally describe the character or desired motion.
contentarray<object>RequiredSupply exactly one reference image and one reference video.
content[].typestringRequiredAccepted values are text, image_url, input_image, video_url, input_video.
content[].textstringConditionalProvide the prompt when the content item has type: "text".
content[].rolestringRequiredUse reference_image for the image and reference_video for the video.
content[].asset_idstringConditionalUpload to POST /v1/videos/assets and use the returned id. Send kind (image, video) before file in the multipart form. The asset must belong to your account. Use its ID or the corresponding public HTTPS URL.
content[].image_urlstringConditionalPublic HTTPS image URL as a plain string.
content[].video_urlstringConditionalPublic HTTPS video URL as a plain string.
motion_modestringOptionalMotion control mode. Accepted values are std, pro. Default: std.
character_orientationstringOptionalThe reference clip must be 3–10 seconds for image and 3–30 seconds for video. Accepted values are image, video. Default: image.
keep_original_soundbooleanOptionalWhether to keep the original audio of the reference clip. Default: true.

Request examples

Set your API key in the local ICODEEASY_API_KEY environment variable and choose an endpoint that accepts direct HTTP calls. For endpoints that require a specific client, follow that client’s setup guide.

Replace example media URLs and asset IDs with your own valid assets.

Video Generations

bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/generations' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "kling-v3-motion-control",
  "prompt": "Preserve the character identity and follow the reference motion.",
  "content": [
    {
      "type": "image_url",
      "image_url": "https://example.com/reference.png",
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": "https://example.com/motion.mp4",
      "role": "reference_video"
    }
  ],
  "motion_mode": "std",
  "character_orientation": "image",
  "keep_original_sound": true
}'

Check video task

bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

Download video

bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID/content' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -L \
  -o result.mp4

Delete a finished video task

bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -i \
  -X DELETE

Responses and tasks

HTTP 202 · Task accepted

json
{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "model": "kling-v3-motion-control",
  "created_at": "2026-07-30T08:00:00Z",
  "status_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "status": "queued",
  "updated_at": "2026-07-30T08:00:00Z",
  "task_id": "vid_1785398400000000000"
}

HTTP 200 · Completed task lookup

json
{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "model": "kling-v3-motion-control",
  "created_at": "2026-07-30T08:00:00Z",
  "status_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "status": "succeeded",
  "updated_at": "2026-07-30T08:01:00Z",
  "url": "/v1/videos/tasks/vid_1785398400000000000/content"
}

Save id. With the same API key, send GET requests to status_url until status is succeeded or failed. On success, download from content_url and follow HTTP redirects. Both paths are relative to the API base URL.

FieldTypeDescription
id / task_idstringTask ID. In the creation response, task_id equals id.
statusstringTask state, one of queued, running, succeeded, or failed.
progressintegerGeneration progress. Omitted when the service has no progress value.
error.codestringError classification for failed tasks.

Common errors

HTTPError typeDescription
400invalid_requestCheck the model, parameter combination, and reference media.
401unauthorizedCheck whether the API key is missing, invalid, or disabled.
402insufficient_balanceThe balance is insufficient to submit the task.
404not_foundIf polling returns 404, keep the task ID and check the polling URL and API key for the account that created the task. It may already have finished. Do not resubmit on this basis.
409video_not_readyThe video is still being generated. Continue polling.
503submission_unknownThe submission outcome is unknown. Contact support to check whether a task was created before sending a new request.

Full integration guide · See the full API guide for request fields, task states, and response formats.

Capabilities and limits

  • text_to_video · Not supported
  • reference_images · Supported
  • video_input · Supported
  • Limits Reference images: up to 1 · Input: One image and one video. Modes: std or pro. Reference video: 3–10 seconds for image orientation, 3–30 seconds for video orientation.

Model Capability Catalog · View pricing

Related guides

Video Generation API

Create video tasks from text, first and last frames, or references; poll status, download results, and delete finished tasks when needed.

Model Capability Catalog

Compare public text, image, and video models by normalized request ID, compatible protocols, supported clients, tool use, media capabilities, limits, and review date.

Sign up and get an API key