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:
      operationId: createKling40VideoTask
      summary: Create a Kling 4.0 task
      description: Submit once; save the
        returned ID and query it.
      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.
  /contents/generations/tasks/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^kling40:[0-9a-f-]{36}$
        description: Complete task ID returned by creation; use the owning GENGEN API key.
    get:
      operationId: retrieveKling40VideoTask
      summary: Retrieve a Kling 4.0 task
      description: Read an existing task without creating a generation. Poll until succeeded or failed.
        Repeated polling does not repeat the generation charge. Query again to renew an expired
        output URL.
      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"
              examples:
                processing:
                  summary: In progress
                  value:
                    id: kling40:01234567-89ab-cdef-0123-456789abcdef
                    model: kling-4.0
                    status: processing
                    outputs:
                      videos: []
                      images: []
                succeeded:
                  summary: Completed video (placeholder URL)
                  value:
                    id: kling40:01234567-89ab-cdef-0123-456789abcdef
                    model: kling-4.0
                    status: succeeded
                    outputs:
                      videos:
                        - https://example.com/generated-video.mp4
                      images: []
                    usage:
                      priceRowId: kling-40-720p-video-input
                      resolution: 720p
                      hasVideoInput: true
                      inputVideoDurationSeconds: 8
                      outputDurationSeconds: 5
                      billableSeconds: 13
                failed:
                  summary: Failed task
                  value:
                    id: kling40:01234567-89ab-cdef-0123-456789abcdef
                    model: kling-4.0
                    status: failed
                    failureReason: Video generation failed.
                    outputs:
                      videos: []
                      images: []
        "400":
          description: Invalid request or incompatible media/mode.
        "401":
          description: Invalid GENGEN API key.
        "402":
          description: Insufficient balance.
        "404":
          description: Task not found or not owned by this API key.
        "429":
          description: Rate limited.
        "502":
          description: Provider response, output or usage needs reconciliation. Query an existing task rather
            than submitting again.
        "503":
          description: Service temporarily unavailable.
  /video/kling/voices:
    get:
      operationId: listKlingVoices
      summary: List Kling voices
      description: Free directory lookup. Use a GENGEN API key from the workspace whose private voices you want to list.
      parameters:
        - name: scope
          in: query
          description: Use preset for official Kling voices or private for active voices created in this workspace.
          schema: { type: string, enum: [preset, private], default: preset }
        - name: page
          in: query
          description: One-based page number. For subsequent requests use the previous response's nextPage.
          schema: { type: integer, minimum: 1, maximum: 1000, default: 1 }
        - name: pageSize
          in: query
          description: Number of entries to request per page.
          schema: { type: integer, minimum: 1, maximum: 100, default: 30 }
      responses:
        "200":
          description: A page of voices from the selected directory.
          content:
            application/json:
              schema:
                type: object
                required: [voices, nextPage]
                properties:
                  voices:
                    type: array
                    description: Voices available on this page. The array can be empty.
                    items:
                      type: object
                      required: [voiceId, name]
                      properties:
                        voiceId: { $ref: "#/components/schemas/VoiceId" }
                        name: { type: string, description: Display name of the voice. }
                        previewUrl: { $ref: "#/components/schemas/VoicePreviewUrl" }
                  nextPage:
                    type: [integer, "null"]
                    description: Next page number, or null when pagination is complete.
              example:
                voices: [{ voiceId: "829837252279803904", name: Laura }]
                nextPage: null
        "400": { description: Invalid scope or pagination. }
        "401": { $ref: "#/components/responses/VoiceUnauthorized" }
    post:
      operationId: createKlingVoice
      summary: Create a private voice
      description: Each accepted creation incurs one request fee, including failed or unresolved clones. Without an Idempotency-Key, each submission creates a separate operation.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: Optional. To retry safely, choose a key before the first request and reuse it with the same body in this workspace. Use printable ASCII without spaces.
          schema: { type: string, minLength: 1, maxLength: 128, pattern: '^[!-~]+$' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [name, sampleUrl]
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 20
                  description: A display name for the private voice, measured after trimming surrounding whitespace.
                  example: Narrator
                sampleUrl:
                  type: string
                  format: uri
                  pattern: '^https://'
                  maxLength: 4096
                  description: Public HTTPS URL for 5–30 seconds of clean speech from one authorized speaker. Supply an MP3, WAV, MP4 or MOV file.
                  example: https://example.com/speaker.wav
      responses:
        "202":
          description: Creation is pending. Poll the returned operationId.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VoiceOperation" }
              example: { operationId: "638f14d6-81ba-49f7-8c21-a16f34dca78f", status: pending, name: Narrator }
        "200":
          description: Current state of a completed creation or an idempotent replay. Inspect status before using voiceId.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VoiceOperation" }
              examples:
                active: { $ref: "#/components/examples/ActiveVoice" }
                failed:
                  value: { operationId: "638f14d6-81ba-49f7-8c21-a16f34dca78f", status: failed, name: Narrator, message: "Kling rejected the voice creation request." }
        "400": { description: Invalid request body or invalid Idempotency-Key value. }
        "401": { $ref: "#/components/responses/VoiceUnauthorized" }
        "402": { description: Insufficient available balance. }
        "403": { description: A billing identity is required. }
        "409": { description: This workspace has already used the key with different input. }
        "413": { description: Request body exceeds 8192 bytes. Send the sample URL in JSON. }
        "429": { description: Private voice capacity reached. }
        "503": { description: Voice creation is currently unavailable. }
  /video/kling/voice-operations/{operationId}:
    get:
      operationId: getKlingVoiceOperation
      summary: Get a voice operation
      description: Free status check for a private voice in the current workspace.
      parameters:
        - name: operationId
          in: path
          required: true
          description: UUID returned by voice creation or deletion. Keep this ID for polling.
          schema: { type: string, format: uuid }
          example: "638f14d6-81ba-49f7-8c21-a16f34dca78f"
      responses:
        "200":
          description: Current state, including pending or deleting. An active voice can be used in Omni.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VoiceOperation" }
              examples:
                active: { $ref: "#/components/examples/ActiveVoice" }
        "401": { $ref: "#/components/responses/VoiceUnauthorized" }
        "404": { description: Unknown operation or operation outside this workspace. }
  /video/kling/voices/{voiceId}:
    delete:
      operationId: deleteKlingVoice
      summary: Delete a private voice
      description: Free deletion. The slot is released once status is deleted.
      parameters:
        - name: voiceId
          in: path
          required: true
          description: String ID from your private voice directory. Use an API key from the owning workspace.
          schema: { $ref: "#/components/schemas/VoiceId" }
      responses:
        "200":
          description: Current voice state. A deleted status confirms removal.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VoiceOperation" }
              example: { operationId: "638f14d6-81ba-49f7-8c21-a16f34dca78f", status: deleted, name: Narrator }
        "202":
          description: Deletion is awaiting confirmation. Poll the returned operationId.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VoiceOperation" }
              example: { operationId: "638f14d6-81ba-49f7-8c21-a16f34dca78f", status: deleting, name: Narrator }
        "401": { $ref: "#/components/responses/VoiceUnauthorized" }
        "404": { description: Unknown voice or voice outside this workspace. }
        "502": { description: Kling rejected the deletion or confirmed it failed. }
components:
  examples:
    ActiveVoice:
      value:
        operationId: "638f14d6-81ba-49f7-8c21-a16f34dca78f"
        status: active
        name: Narrator
        voiceId: "839000000000000001"
        previewUrl: https://example.com/narrator-preview.wav
  responses:
    VoiceUnauthorized:
      description: A valid GENGEN bearer API key is required.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: GENGEN API key
  schemas:
    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.
    VoicePreviewUrl:
      type: string
      format: uri
      description: Optional HTTPS link to an audio preview. Open it to listen to the voice.
    VoiceOperation:
      type: object
      required: [operationId, status, name]
      properties:
        operationId:
          type: string
          format: uuid
          description: Stable workspace voice operation ID. Use it in the voice-operations path to check progress.
        status:
          type: string
          enum: [pending, active, failed, deleting, deleted]
          description: Pending and deleting require polling. Active means ready for Omni, failed means creation failed, and deleted confirms removal.
        name: { type: string, description: Display name supplied at creation. }
        voiceId:
          $ref: "#/components/schemas/VoiceId"
          description: Returned when active. Copy this string into an Omni request or the delete endpoint.
        previewUrl: { $ref: "#/components/schemas/VoicePreviewUrl" }
        message:
          type: string
          description: Additional detail about a failure or a deletion awaiting confirmation.
    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
    MediaUrl:
      type: string
      format: uri
      pattern: ^https://
      maxLength: 4096
      description: Accessible HTTPS URL without username/password.
    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
    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.
    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
