> ## 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.

# Upload Audio

> Uploads an audio file and returns a `file_id` for cloning. Files are scoped to the workspace.

`multipart/form-data`, field name `file`. Supported types: `audio/wav`, `audio/mpeg`, `audio/mp3`, `audio/mp4`, `audio/ogg`, `audio/webm`. Maximum 10MB.

Clone sample requirements: 10–20 seconds recommended (60 seconds max), WAV (16bit) / MP3 / M4A, sample rate ≥16kHz, mono or stereo (first channel only), with at least 5 seconds of continuous clear speech.

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

    | Case | Error code |
    | - | - |
    | Missing `file` field | `20010 missing file field` |
    | Empty file | `20006 empty file` |
    | Larger than 10MB | `20007 file too large` |
    | Unsupported audio type | `20008 unsupported media type` |
    | Invalid multipart form | `20009 invalid multipart form` |
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml streaming-avatar/api-references/openapi.json POST /v1/files/audios
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/files/audios:
    post:
      summary: Upload Audio
      description: >-
        Uploads an audio file and returns a `file_id` for cloning. Files are
        scoped to the workspace.


        `multipart/form-data`, field name `file`. Supported types: `audio/wav`,
        `audio/mpeg`, `audio/mp3`, `audio/mp4`, `audio/ogg`, `audio/webm`.
        Maximum 10MB.


        Clone sample requirements: 10–20 seconds recommended (60 seconds max),
        WAV (16bit) / MP3 / M4A, sample rate ≥16kHz, mono or stereo (first
        channel only), with at least 5 seconds of continuous clear speech.
      operationId: uploadAudio
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  contentMediaType: application/octet-stream
                  description: >-
                    Audio file. Supported types: `audio/wav`, `audio/mpeg`,
                    `audio/mp3`, `audio/mp4`, `audio/ogg`, `audio/webm`. Maximum
                    10MB; WAV (16bit) / MP3 are recommended.
      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:
                      file_id:
                        type: string
                        description: >-
                          File id, shaped like `file_aud_…`. Pass this as
                          `file_id` when cloning.
                      file_type:
                        type: string
                        description: Always `audio`.
                      mime_type:
                        type: string
                        description: Detected MIME type.
                      size_bytes:
                        type: integer
                        description: File size.
                      url:
                        type: string
                        description: CDN URL.
                      created_at:
                        type: string
                        format: date-time
                        description: Creation time.
                    required:
                      - file_id
                      - file_type
                      - mime_type
                      - size_bytes
                      - url
                      - created_at
              example:
                code: 0
                message: success
                data:
                  file_id: file_aud_a1b2c3d4e5f6
                  file_type: audio
                  mime_type: audio/mpeg
                  size_bytes: 335822
                  url: >-
                    https://static.vivi-x.ai/audios/2026/08/02/febd902cac2a6f57.mp3
                  created_at: '2026-08-02T10:00:00Z'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Vivix API key. Keep it on your server.

````