> ## 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 private Kling voice

> Clone one speaker from an authorized sample and use the result in Kling 4.0 Omni.

Give the voice a display `name` and set `sampleUrl` to a public HTTPS link to your own recording. Use 5–30 seconds of clean speech from one speaker whose voice you have permission to replicate. MP3, WAV, MP4 and MOV are supported.

* **HTTP 202, `pending`** — Copy `operationId` into [Get voice operation](https://docs.gengen.farm/api-reference/kling/4.0/get-voice-operation.md) to check progress.
* **HTTP 200, `active`** — Use `voiceId` in `assets.voices[].voiceId` and listen to `previewUrl` if provided. See the [Omni request example](https://docs.gengen.farm/api-reference/kling/4.0/voices.md).
* **HTTP 200, `failed`** — Read `message` for the reason. Submit a corrected sample as a new creation.

**Billing and limits.** Sending a new request in Try it can charge your wallet. Each accepted creation is billed once at your applicable **Custom voice creation** rate, including failed clones and unresolved upstream responses. Kling's official base rate is \$0.007 per request. Rejections before acceptance are free. Listing, status checks and deletion are free. Referencing the voice in Omni adds no separate voice fee. [Pricing](https://docs.gengen.farm/pricing.md)

**Retrying a request.** The `Idempotency-Key` header is optional. Without it, each accepted submission creates a separate operation and incurs a charge, even for the same sample. For safe retries, send a key on the first request and reuse it with the same body. GENGEN then returns the original operation without another charge. Reusing a key with different input returns HTTP 409.

Each workspace has five private voice slots. Pending and active voices, as well as voices awaiting deletion, occupy slots.


## OpenAPI

````yaml openapi/kling-40-video.yaml POST /video/kling/voices
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:
  /video/kling/voices:
    post:
      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.
      operationId: createKlingVoice
      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:
        '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.
        '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
        '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.
components:
  schemas:
    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.
    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.
  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

````

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