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

# Clone Voice

> Clones a voice from an uploaded audio `file_id` and returns a `voice_id`. Pass that id as `pipeline_config.tts_config.tts_voice_id` when you start a session.

<AccordionGroup>
  <Accordion title="Use the voice when you create a session">
    ```json theme={null}
    {
      "pipeline_config": {
        "tts_config": {
          "tts_voice_id": "voice_9f1c2a7b"
        }
      }
    }
    ```

    Only the `tts_voice_id` is required: the service fills `tts_provider` / `tts_model_id` for that voice.
  </Accordion>

  <Accordion title="Errors">
    Error responses use the same `{code, message, data}` envelope; a non-zero `code` identifies the error.

    | Case | Error code |
    | - | - |
    | Missing `name` or `file_id` | `20003 missing required parameter` |
    | `language` / `name` is invalid | `20004 invalid parameter` |
    | `file_id` does not exist or is not in the current workspace | `20005 not found` |
    | `file_id` is not an audio file | `20004 invalid parameter` |
    | The clone `provider` call failed (HTTP 502) | `30007 voice clone provider failed` |
    | The API key is missing or invalid | `10001 missing api key` or `10003 invalid api key` |
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml streaming-avatar/api-references/openapi.json POST /v1/voices
openapi: 3.1.0
info:
  title: Vivix Streaming Avatar API
  version: 1.0.0
  description: REST endpoints for Streaming Avatar sessions, voices, and characters.
servers:
  - url: https://api.vivix.ai
security:
  - bearerAuth: []
paths:
  /v1/voices:
    post:
      summary: Clone Voice
      description: >-
        Clones a voice from an uploaded audio `file_id` and returns a
        `voice_id`. Pass that id as `pipeline_config.tts_config.tts_voice_id`
        when you start a session.
      operationId: cloneVoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Display name, at most 128 characters.
                file_id:
                  type: string
                  description: >-
                    Audio file id in the current workspace (call Upload Audio
                    first).
                language:
                  type: string
                  description: >-
                    Sample `language`: `zh` (Chinese), `en` (English), `fr`
                    (French), `de` (German), `ja` (Japanese), `ko` (Korean),
                    `ru` (Russian), `pt` (Portuguese), `th` (Thai), `id`
                    (Indonesian), `vi` (Vietnamese), `it` (Italian), `es`
                    (Spanish), `ms` (Malay), `fil` (Filipino), `ar` (Arabic).
              required:
                - name
                - file_id
            example:
              name: Studio Host
              file_id: file_aud_a1b2c3d4e5f6
              language: zh
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                  - data
                properties:
                  code:
                    type: integer
                    description: '`0` on success; any other value is an error code.'
                  message:
                    type: string
                    description: '`success`, or an English error description.'
                  data:
                    type: object
                    properties:
                      voice_id:
                        type: string
                        description: >-
                          Voice id (shaped like `voice_…`). Pass it unchanged as
                          `tts_voice_id`.
                      name:
                        type: string
                        description: Display name.
                      language:
                        type: string
                        description: Language sent on create; empty string when omitted.
                    required:
                      - voice_id
                      - name
                      - language
              example:
                code: 0
                message: success
                data:
                  voice_id: voice_9f1c2a7b
                  name: Studio Host
                  language: zh
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Vivix API key. Keep it on your server.

````