> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gengen.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Kling 4.0 task

> Normalized text, keyframe and Omni requests.

See the [workflow guide](https://docs.gengen.farm/api-reference/kling/4.0/overview.md) for examples, media requirements and billing rules. Use a GENGEN API key.

For pending tasks, poll the returned ID. The successful task detail includes `usage` with billable seconds and the applicable price row. See [usage fields](https://docs.gengen.farm/api-reference/kling/4.0/retrieve-task.md#usage).


## OpenAPI

````yaml openapi/kling-40-video.yaml POST /contents/generations/tasks
openapi: 3.1.0
info:
  title: Kling 4.0 Video API
  version: 1.0.0
  description: >-
    Supports text-to-video, image keyframes and Omni references/editing.
    Authenticate with a GENGEN API key.
servers:
  - url: https://gengen.farm/api/gengen/v1
security:
  - bearerAuth: []
paths:
  /contents/generations/tasks:
    post:
      summary: Create a Kling 4.0 task
      description: Submit once; save the returned ID and query it.
      operationId: createKling40VideoTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
            examples:
              workflow0:
                summary: Text to video
                value:
                  model: kling-4.0
                  mode: text_to_video
                  prompt: Ocean waves at sunrise, with gentle surf sounds.
                  controls:
                    duration: 10
                    resolution: 1080p
                    watermark: false
                    ratio: '16:9'
              workflow1:
                summary: First frame
                value:
                  model: kling-4.0
                  mode: image_to_video
                  prompt: Animate @firstFrame1 with a slow camera push.
                  assets:
                    firstFrameImage:
                      url: https://example.com/firstFrame1.png
                      id: firstFrame1
                  controls:
                    duration: 10
                    resolution: 1080p
                    watermark: false
              workflow2:
                summary: First and last frames
                value:
                  model: kling-4.0
                  mode: image_to_video
                  prompt: Transition smoothly from @firstFrame1 to @lastFrame1.
                  assets:
                    firstFrameImage:
                      url: https://example.com/firstFrame1.png
                      id: firstFrame1
                    lastFrameImage:
                      url: https://example.com/lastFrame1.png
                      id: lastFrame1
                  controls:
                    duration: 10
                    resolution: 1080p
                    watermark: false
              workflow3:
                summary: Multiple keyframes
                value:
                  model: kling-4.0
                  mode: image_to_video
                  prompt: Move from @firstFrame1 through @middleFrame1 to @lastFrame1.
                  assets:
                    firstFrameImage:
                      url: https://example.com/firstFrame1.png
                      id: firstFrame1
                    middleFrameImages:
                      - url: https://example.com/middleFrame1.png
                        id: middleFrame1
                    lastFrameImage:
                      url: https://example.com/lastFrame1.png
                      id: lastFrame1
                  controls:
                    duration: 10
                    resolution: 1080p
                    watermark: false
              workflow4:
                summary: Omni references
                value:
                  model: kling-4.0
                  mode: omni_video
                  prompt: >-
                    Animate the character in @image1 using the motion of
                    @video1.
                  assets:
                    referenceImages:
                      - url: https://example.com/image1.png
                        id: image1
                    referenceVideos:
                      - url: https://example.com/video1.mp4
                        id: video1
                  controls:
                    duration: 10
                    resolution: 1080p
                    watermark: false
                    ratio: adaptive
              workflow5:
                summary: Video editing
                value:
                  model: kling-4.0
                  mode: omni_video
                  prompt: Restyle @sourceVideo1 using the colors of @image1.
                  assets:
                    sourceVideo:
                      url: https://example.com/sourceVideo1.mp4
                      id: sourceVideo1
                    referenceImages:
                      - url: https://example.com/image1.png
                        id: image1
                  controls:
                    duration: 10
                    resolution: 1080p
                    watermark: false
                    ratio: adaptive
      responses:
        '200':
          description: >-
            Task status. Save the complete public ID. Success is delivered after
            output storage and settlement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              example:
                id: kling40:01234567-89ab-cdef-0123-456789abcdef
                model: kling-4.0
                status: pending
                outputs:
                  videos: []
                  images: []
        '400':
          description: Invalid request or incompatible media/mode.
        '401':
          description: Invalid GENGEN API key.
        '402':
          description: Insufficient balance.
        '429':
          description: Rate limited.
        '502':
          description: >-
            Provider response, output or usage needs reconciliation. Query an
            existing task rather than submitting again.
        '503':
          description: Currently unavailable.
          content:
            application/json:
              example:
                error_code: gengen.model_temporarily_unavailable
                error: Kling 4.0 is temporarily unavailable.
components:
  schemas:
    Request:
      type: object
      additionalProperties: false
      properties:
        model:
          type: string
          enum:
            - kling-4.0
          description: Use `kling-4.0`.
        mode:
          type: string
          enum:
            - text_to_video
            - image_to_video
            - omni_video
          description: >
            Optional. Supported values:


            - `text_to_video`: Generate from a text prompt without reference
            media.

            - `image_to_video`: Generate from one or more keyframe images
            (first, middle or last frames).

            - `omni_video`: Generate or edit using image/video references, a
            source video, elements or voices. Keyframes are also supported.


            If omitted, reference images/videos, a source video, elements or
            voices select `omni_video`;

            otherwise keyframes select `image_to_video`, and text alone selects
            `text_to_video`.
        prompt:
          type: string
          minLength: 1
          description: >-
            Nonblank text. Weighted limit: ASCII code points / 26000 + other
            Unicode code points / 11000 <= 1. Use @referenceId to refer to
            media. Describe dialogue, music and sound effects here. Include
            positive and negative descriptions in this field. Specify what to
            preserve and what to change when editing.
        assets:
          $ref: '#/components/schemas/Assets'
        controls:
          $ref: '#/components/schemas/Controls'
        providerOptions:
          type: object
          additionalProperties: false
          properties: {}
      required:
        - model
        - prompt
    Task:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          pattern: ^kling40:[0-9a-f-]{36}$
        model:
          type: string
          enum:
            - kling-4.0
          description: Always `kling-4.0`.
        status:
          type: string
          enum:
            - pending
            - processing
            - succeeded
            - failed
          description: >
            - `pending`: Task accepted and awaiting processing.

            - `processing`: Generation, output storage or billing settlement is
            in progress.

            - `succeeded`: Output is stored and billing is settled; read
            `outputs.videos`.

            - `failed`: Task failed; see `failureReason`.
        outputs:
          type: object
          additionalProperties: false
          properties:
            videos:
              type: array
              items:
                type: string
                format: uri
              description: >-
                One video URL on success; empty while pending/processing or
                failed. Links expire: copy outputs to your storage or retrieve
                the task again.
            images:
              type: array
              items:
                type: string
          required:
            - videos
            - images
        usage:
          type: object
          description: >-
            Successful task detail. With video input, billable seconds equal
            output seconds plus the greater of input and output seconds.
            Otherwise only output seconds are charged.
          required:
            - priceRowId
            - resolution
            - billableSeconds
            - outputDurationSeconds
            - inputVideoDurationSeconds
            - hasVideoInput
          properties:
            priceRowId:
              type: string
              description: Stable customer price row in GET /api/public/pricing.
            resolution:
              type: string
              description: Resolution tier used for pricing, such as 720p.
            billableSeconds:
              type: number
              description: Seconds to multiply by the selected per-second rate.
            outputDurationSeconds:
              type: number
              description: Output video duration in seconds.
            inputVideoDurationSeconds:
              type: number
              description: Input video seconds used for billing.
            hasVideoInput:
              type: boolean
              description: Whether the video input rate applies.
        createdAt:
          type: string
          format: date-time
        failureReason:
          type: string
          description: Present when the task fails.
      required:
        - id
        - model
        - status
        - outputs
    Assets:
      type: object
      additionalProperties: false
      properties:
        firstFrameImage:
          $ref: '#/components/schemas/MediaReference'
          description: >-
            First keyframe image, for image_to_video or omni_video. Default
            reference ID is firstFrame1.
        middleFrameImages:
          type: array
          items:
            $ref: '#/components/schemas/MediaReference'
          maxItems: 10
          description: >-
            Middle keyframe images, for image_to_video or omni_video. Default
            IDs are middleFrame1, middleFrame2, and so on. The ten-image limit
            includes first/last frames and reference images.
        lastFrameImage:
          $ref: '#/components/schemas/MediaReference'
          description: >-
            Last keyframe image, for image_to_video or omni_video. Default
            reference ID is lastFrame1.
        referenceImages:
          type: array
          items:
            $ref: '#/components/schemas/MediaReference'
          maxItems: 10
          description: >-
            Omni only; appearance, scene or style references. Default IDs are
            image1, image2, and so on.
        referenceVideos:
          type: array
          items:
            $ref: '#/components/schemas/MediaReference'
          maxItems: 5
          description: >-
            Omni only; motion/content references. Default IDs are video1,
            video2, and so on.
        sourceVideo:
          $ref: '#/components/schemas/MediaReference'
          description: >-
            Omni only; at most one video to edit. Default reference ID is
            sourceVideo1.
        elements:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              elementId:
                type: string
                minLength: 1
                maxLength: 128
                pattern: ^[a-zA-Z0-9_-]+$
              id:
                type: string
                minLength: 1
                maxLength: 128
                pattern: ^[a-zA-Z0-9_-]+$
            required:
              - elementId
              - id
          maxItems: 7
          description: >-
            Omni only. Use existing official preset IDs, verified by the
            service.
        voices:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              voiceId:
                $ref: '#/components/schemas/VoiceId'
              id:
                description: >-
                  Name you choose for this reference in the current request. For
                  example, use narrator here and @narrator in the prompt.
                type: string
                minLength: 1
                maxLength: 128
                pattern: ^[a-zA-Z0-9_-]+$
            required:
              - voiceId
              - id
          maxItems: 3
          description: >-
            Omni only. Use a voiceId from GET /video/kling/voices (official
            presets or active private voices in the same workspace). Voice
            references incur no additional charge.
      description: >-
        At most 10 images and 15 total references across all fields. At most
        five video inputs (including source video and video elements), at most
        three video elements, and at most 30 seconds of combined input video.
        Image-to-video requires at least one keyframe. Text-to-video uses the
        prompt alone; reference images/videos, elements and voices require Omni.
        Images must be JPEG/PNG, at most 30 MiB each, at least 300 pixels per
        side, with an aspect ratio from 2:5 to 5:2. Videos must be MP4/MOV, at
        most 300 MiB each, 3–30 seconds, 24–60 fps, 700–4553 pixels per side, at
        most 8,294,400 pixels, with an aspect ratio from 2:5 to 5:2.
    Controls:
      type: object
      additionalProperties: false
      properties:
        duration:
          type: integer
          minimum: 3
          maximum: 30
          description: >-
            Output seconds, an integer from 3 to 30. An explicit value overrides
            the prompt. If omitted, the model follows the prompt's duration
            instruction; without one, Omni uses the source video's duration when
            present, otherwise the default is 10 seconds. Estimates/reservations
            use the 30-second maximum when omitted. Final billing uses measured
            duration.
        resolution:
          type: string
          enum:
            - 720p
            - 1080p
          default: 1080p
          description: 'Supported values: `720p`, `1080p` (default).'
        ratio:
          type: string
          enum:
            - '21:9'
            - '16:9'
            - '9:16'
            - '1:1'
            - adaptive
          description: >
            Supported values: `21:9`, `16:9`, `9:16`, `1:1`, and `adaptive`
            (Omni only).


            Omit for image-to-video: keyframes determine aspect ratio.
            Text-to-video defaults to `16:9`.

            Omni defaults to `adaptive`; an explicit ratio overrides the prompt.

            With `adaptive`, precedence is the prompt's ratio instruction,
            source video, keyframe images,

            other input videos, then `16:9`. The first frame takes precedence
            among keyframes;

            without it, the first supplied keyframe is used.
        watermark:
          type: boolean
          default: false
          description: Return the watermarked video in outputs.videos when true.
    MediaReference:
      description: >-
        Accessible HTTPS URL without embedded credentials, or URL plus a unique
        reference ID. Use @id in the prompt. All task reference IDs must be
        unique.
      oneOf:
        - $ref: '#/components/schemas/MediaUrl'
        - type: object
          additionalProperties: false
          properties:
            url:
              $ref: '#/components/schemas/MediaUrl'
            id:
              type: string
              minLength: 1
              maxLength: 128
              pattern: ^[a-zA-Z0-9_-]+$
          required:
            - url
    VoiceId:
      type: string
      minLength: 1
      maxLength: 128
      pattern: ^[A-Za-z0-9_-]+$
      description: >-
        Kling's voice ID. Preserve it as a string, including when it contains
        only digits. Pass it in assets.voices[].voiceId.
    MediaUrl:
      type: string
      format: uri
      pattern: ^https://
      maxLength: 4096
      description: Accessible HTTPS URL without username/password.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: GENGEN API key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.