> ## Documentation Index
> Fetch the complete documentation index at: https://developers.x-pilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# clone voice

> Clone a private voice from audio already uploaded to your account. Voice I (default) is an instant clone from one sample. Voice II needs the speaker's consent: call get_voice_clone_config, have the speaker record the consent_statement for the chosen locale with their name and company_name filled in, upload it separately, then pass voice_talent_name, locale, consent_audio_url and consent_accepted=true. Never fabricate consent or set consent_accepted without the speaker's explicit agreement. Voice II returns 403 voice_ii_unavailable while cloning is not open for the account. Poll get_voice until state is trained or failed. Reuse Idempotency-Key on retry.

export const XpilotArticleMetadata = () => <script type="application/ld+json" data-xpilot-article-metadata="" dangerouslySetInnerHTML={{
  __html: "{\"@context\":\"https://schema.org\",\"@id\":\"https://developers.x-pilot.ai/api-reference/clone-voice#apireference\",\"author\":{\"@type\":\"Organization\",\"@id\":\"https://www.x-pilot.ai/#organization\",\"name\":\"X-Pilot\",\"url\":\"https://www.x-pilot.ai/\"},\"image\":{\"@type\":\"ImageObject\",\"url\":\"https://developers.x-pilot.ai/images/integration-api.png\",\"width\":1200,\"height\":675,\"caption\":\"REST requests use a scoped API key. Keys, credits and usage are managed in the App console.\"}}"
}} />;

<XpilotArticleMetadata />

export const XpilotBreadcrumb = () => <nav aria-label="Breadcrumb" className="xpilot-breadcrumb"><ol><li><a href="/api-reference/list-voices">Voices & audio</a></li><li aria-current="page"><span aria-hidden="true">/</span><span>clone voice</span></li></ol></nav>;

<XpilotBreadcrumb />

<p className="xpilot-doc-author">Documentation by <a href="https://www.x-pilot.ai/">X-Pilot</a></p>

Required scope: `audio:write`. A stable `Idempotency-Key` is required for exact retries.

[Manage API keys](https://app.x-pilot.ai/developers/console) · [Authentication and recovery](/api-reference)

export const XpilotDocFigure = () => <figure className="xpilot-doc-figure"><img src="/images/integration-api.png" alt="An application sends a scoped API key to the X-Pilot REST API and receives an HTTP status and JSON response." width="1200" height="675" loading="lazy" /><figcaption>REST requests use a scoped API key. Keys, credits and usage are managed in the App console.</figcaption></figure>;

<XpilotDocFigure />


## OpenAPI

````yaml openapi.json POST /v1/voices/clone
openapi: 3.0.3
info:
  title: X-Pilot Developer API
  version: 1.1.0
  description: >-
    Generated from the same public REST contract used by the X-Pilot app. REST
    uses scoped API Keys. MCP OAuth tokens do not authenticate REST requests.
servers:
  - url: https://api.x-pilot.ai
    description: Production; confirm the deployed base URL in Developer Console.
security:
  - BearerAuth: []
tags:
  - name: Video Agent
  - name: Renders
  - name: Brand kits
  - name: Account & capacity
  - name: Assets
  - name: Voices & audio
  - name: Avatars
paths:
  /v1/voices/clone:
    post:
      tags:
        - Voices & audio
      summary: clone voice
      description: >-
        Clone a private voice from audio already uploaded to your account. Voice
        I (default) is an instant clone from one sample. Voice II needs the
        speaker's consent: call get_voice_clone_config, have the speaker record
        the consent_statement for the chosen locale with their name and
        company_name filled in, upload it separately, then pass
        voice_talent_name, locale, consent_audio_url and consent_accepted=true.
        Never fabricate consent or set consent_accepted without the speaker's
        explicit agreement. Voice II returns 403 voice_ii_unavailable while
        cloning is not open for the account. Poll get_voice until state is
        trained or failed. Reuse Idempotency-Key on retry.
      operationId: clone-voice
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Stable key for exact retries only. Use a different key for a
            different operation or input.
          schema:
            type: string
            minLength: 8
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Voice title.
                  maxLength: 80
                audio_url:
                  type: string
                  description: >-
                    Owned uploaded training audio URL. Voice II: 5–90 seconds of
                    the same speaker.
                cover_image_url:
                  type: string
                  description: Optional owned uploaded cover image URL. Voice I only.
                voice_version:
                  type: integer
                  description: >-
                    Voice I (1, default) or Voice II (2, consent-based personal
                    voice).
                  enum:
                    - 1
                    - 2
                  default: 1
                voice_talent_name:
                  type: string
                  description: >-
                    Voice II only: the speaker's name exactly as spoken in the
                    consent recording.
                  maxLength: 128
                locale:
                  type: string
                  description: >-
                    Voice II only: recording locale from get_voice_clone_config,
                    for example en-US or zh-CN.
                  maxLength: 16
                consent_audio_url:
                  type: string
                  description: >-
                    Voice II only: owned uploaded recording of the speaker
                    reading the consent_statement for locale. Must be a separate
                    file from audio_url, at most 90 seconds.
                consent_accepted:
                  type: boolean
                  description: >-
                    Voice II only: true when the speaker has explicitly agreed
                    that their voice may be cloned. Required for Voice II.
                  enum:
                    - true
                    - false
              required:
                - name
                - audio_url
      responses:
        '202':
          description: Success
          content:
            application/json:
              example:
                data:
                  _id: <voice_id>
                  title: My clone
                  voice_version: 2
                  state: training
                  selectable: false
        '400':
          description: Check parameter types, required fields and idempotency key.
          content:
            application/json:
              example:
                error:
                  code: invalid_parameter
                  message: Check parameter types, required fields and idempotency key.
                request_id: <request_id>
        '401':
          description: Use an active scoped API Key. MCP OAuth tokens cannot call REST.
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: >-
                    Use an active scoped API Key. MCP OAuth tokens cannot call
                    REST.
                request_id: <request_id>
        '403':
          description: Check the credential scope and resource ownership.
          content:
            application/json:
              example:
                error:
                  code: insufficient_scope
                  message: Check the credential scope and resource ownership.
                request_id: <request_id>
        '409':
          description: >-
            The same idempotency key must use the exact same input. A
            conversation may already be busy.
          content:
            application/json:
              example:
                error:
                  code: idempotency_conflict
                  message: >-
                    The same idempotency key must use the exact same input. A
                    conversation may already be busy.
                request_id: <request_id>
        '429':
          description: >-
            Credential/workspace rate or concurrency limit reached. Respect
            Retry-After before retrying.
          content:
            application/json:
              example:
                error:
                  code: rate_limited
                  message: >-
                    Credential/workspace rate or concurrency limit reached.
                    Respect Retry-After before retrying.
                  retry_after: 60
                request_id: <request_id>
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --fail-with-body --request POST \
              --url "$XPILOT_API_BASE_URL/v1/voices/clone" \
              --header "Authorization: Bearer $XPILOT_API_KEY" \
              --header 'Content-Type: application/json' \
              --header 'Idempotency-Key: lesson-request-001' \
              --data '{"name":"<name>","audio_url":"<audio_url>","voice_version":1}'
        - lang: javascript
          label: JavaScript
          source: >-
            const response = await fetch(process.env.XPILOT_API_BASE_URL +
            "/v1/voices/clone", {
              method: "POST",
              headers: {
                Authorization: `Bearer ${process.env.XPILOT_API_KEY}`,
                "Content-Type": "application/json",
                "Idempotency-Key": "lesson-request-001",
              },
              body: JSON.stringify({
              "name": "<name>",
              "audio_url": "<audio_url>",
              "voice_version": 1
            }),

            });

            const result = await response.json();

            if (!response.ok) throw new Error(JSON.stringify(result));

            console.log(result);
        - lang: python
          label: Python
          source: |-
            import os, json, requests

            response = requests.request(
                "POST",
                os.environ["XPILOT_API_BASE_URL"] + "/v1/voices/clone",
                headers={
                    "Authorization": "Bearer " + os.environ["XPILOT_API_KEY"],
                    "Content-Type": "application/json",
                    "Idempotency-Key": "lesson-request-001",
                },
                json=json.loads("{\"name\":\"<name>\",\"audio_url\":\"<audio_url>\",\"voice_version\":1}"),
                timeout=70,
            )
            print(response.status_code, response.text)
            response.raise_for_status()
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Scoped X-Pilot API key

````

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