Create video

Create Kling 4.0 text-to-video, image-to-video, or Omni tasks using the platform format.

Use the common fields for basic inputs and metadata.contents for advanced inputs. Put generation settings in metadata.settings and callback and watermark options in metadata.options.

POST/v1/video/generations

Create video using platform fields and configure text-to-video, image-to-video, or Omni through metadata. The alias POST /v1/videos/generations accepts the same parameters. All three operations use kling-4.0; Omni denotes multi-reference capabilities, not a separate model.

Authorization

bearerAuth

AuthorizationBearer <token>

Use a platform API Key: Authorization: Bearer your-api-key.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Provide prompts and assets through prompt or metadata.contents as appropriate for the operation. Do not put native fields directly at the top level of platform requests.

model*"kling-4.0"

All three operations use the same Kling 4.0 model.

Default"kling-4.0"

Value in

"kling-4.0"

prompt?Prompt

Prompts may contain positive and negative descriptions. English-only input allows up to 26000 characters, non-English-only input up to 11000. Mixed input must satisfy E/26000 + N/11000 <= 1, where E and N count English and non-English characters.

image?string

Single reference image URL; image-to-video shortcut.

images?array<string>

One image means a first frame; two mean first and last frames. Submit additional frames through typed metadata.contents.

duration?integer

Duration shortcut in seconds. Explicit metadata.settings takes precedence.

Range3 <= value <= 30

seconds?integer

Platform duration shortcut. Use only one duration representation; explicit metadata.settings takes precedence.

Range3 <= value <= 30

size?string

Resolution shortcut: 720p or 1080p, not pixel dimensions. Prefer metadata.settings.resolution and avoid supplying size as well.

Value in

"720p"
"1080p"

metadata?

Native extension configuration. Explicit settings takes precedence; supplied false and 0 are retained, but values must satisfy the native operation's field constraints.

Response Body

`application/json`

curl -X POST "https://api.agtcloud.cn/v1/video/generations" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0",
    "prompt": "A sunlit coastal technology park; the camera slowly circles white buildings.",
    "metadata": {
      "operation": "text-to-video",
      "settings": {
        "duration": 3,
        "resolution": "720p"
      },
      "options": {
        "watermark_info": {
          "enabled": false
        }
      }
    }
  }'

{
  "id": "123456789012345678",
  "task_id": "123456789012345678",
  "object": "video",
  "model": "kling-4.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1792732542
}

Creation results and retrieval

Creation returns a top-level task object. id and task_id are task IDs represented as strings. Save task_id and use the platform retrieval API to obtain the status and video URL.

status: "queued" means the task was accepted and queued; progress: 0 does not indicate failure. The creation response does not contain the final video URL. created_at is a Unix timestamp in seconds, unlike the millisecond timestamps in native responses.

Choose an input format

Scenario	Input	Detailed rules
Text-to-video	`prompt`; specify `metadata.operation: "text-to-video"` for advanced configuration	Text-to-video parameters
Image-to-video	`image` / `images`, or typed `metadata.contents`; operation: `image-to-video`	Image sources and keyframe limits
Omni reference or editing	Use `metadata.operation: "omni-video"` and `metadata.contents`	Asset types, references, and combination limits

Explicit metadata.settings takes precedence over shortcut fields. Asset reference id is optional for images and videos; reference id is required for elements and voices. All supplied asset reference IDs must be unique within the task.

Common errors and troubleshooting

Response or error	What to check
HTTP 401, `Invalid token`	Check `Authorization: Bearer your-api-key` and use a valid API Key for the requested site
HTTP 400, `模型名称不能为空`	Set `model: "kling-4.0"`
HTTP 400, `prompt cannot be empty`	Text-to-video requires a nonempty `prompt`; use `metadata.contents` according to the corresponding native operation for advanced inputs
HTTP 400, `duration must be an integer`	Use an integer such as `3`, not the string `"3"` or a decimal
`settings.resolution ... is invalid`	Use `720p` or `1080p`, not pixel dimensions; remove `size` and use `metadata.settings.resolution` consistently
HTTP 400, `invalid JSON request body`	Check quotes, commas, and brackets; the body must be valid JSON without comments

HTTP 400 may return code/message/data or an error object. During creation, code: "fail_to_fetch_task" may also indicate upstream parameter validation failure. Read the specific cause in message instead of repeatedly retrying based on the business code alone.

message may be a JSON string containing code/message/request_id, not an already parsed object; check the format before parsing. Keep the request ID for support, but do not share your API Key. Refer to the corresponding native operation for input limits; ranges in generic validation errors do not define model capabilities.

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

Creation results and retrieval

Choose an input format

Common errors and troubleshooting

`application/json`

`application/json`

`application/json`