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

# Create custom voice

> Create a custom voice clone from reference audio (`multipart/form-data`). Required fields: `name`, `language`, `file` (audio upload, max 31 MB / 120 s), `consent_attestation=true`. Requires `customVoicesEnabled` org gate and an xAI Enterprise contract. US only, except Illinois. Creation is subject to the shared xAI team capacity.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/custom-voices
openapi: 3.0.3
info:
  title: AI Reserve Gateway API
  description: >-
    The AI Reserve API surface — OpenAI-compatible chat completions,
    Anthropic-compatible messages, Bedrock Converse, images, video, files,
    text-to-speech, realtime voice sessions, and GPU Compute pod/volume
    management — all behind one endpoint and one API key.
  version: 1.0.0
servers:
  - url: https://api.aireserve.com
security:
  - bearerAuth: []
paths:
  /v1/custom-voices:
    post:
      tags:
        - Audio
      summary: Create custom voice
      description: >-
        Create a custom voice clone from reference audio
        (`multipart/form-data`). Required fields: `name`, `language`, `file`
        (audio upload, max 31 MB / 120 s), `consent_attestation=true`. Requires
        `customVoicesEnabled` org gate and an xAI Enterprise contract. US only,
        except Illinois. Creation is subject to the shared xAI team capacity.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - name
                - language
                - file
                - consent_attestation
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Display name for this custom voice.
                language:
                  type: string
                  description: BCP-47 language code (e.g. `en`, `en-US`).
                file:
                  type: string
                  format: binary
                  description: >-
                    Reference audio file. Recommended: single-speaker mono WAV
                    at 24 kHz, 90–120 s, quiet environment. Max 31 MB / 120 s.
                consent_attestation:
                  type: string
                  enum:
                    - 'true'
                  description: >-
                    Must be `"true"`. Attests that the speaker has given
                    informed consent to having their voice cloned.
                description:
                  type: string
                  maxLength: 10000
                  description: Optional free-text description.
                gender:
                  type: string
                  enum:
                    - male
                    - female
                    - neutral
                  description: Speaker gender.
                accent:
                  type: string
                  maxLength: 100
                  description: Speaker accent (free text).
                age:
                  type: string
                  enum:
                    - young
                    - middle-aged
                    - old
                  description: Approximate speaker age bracket.
                use_case:
                  type: string
                  enum:
                    - conversational
                    - narration
                    - characters
                    - educational
                    - advertisement
                    - social_media
                    - entertainment
                  description: Intended use-case hint for voice model tuning.
                tone:
                  type: string
                  enum:
                    - warm
                    - casual
                    - professional
                    - friendly
                    - authoritative
                    - expressive
                    - calm
                  description: Tonal quality hint.
      responses:
        '201':
          description: Custom voice created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamVoiceView'
              example:
                voice_id: ab3f9c2e
                name: Product narrator
                language: en-US
                tone: warm
                use_case: narration
                created_at: '2026-09-03T21:00:00.000Z'
        '403':
          description: '`customVoicesEnabled` or xAI Enterprise contract is inactive.'
        '409':
          description: Custom voice creation capacity is currently unavailable.
        '413':
          description: Reference audio exceeds the 31 MB / 120 s limit.
components:
  schemas:
    UpstreamVoiceView:
      type: object
      description: >-
        Allowlisted projection of an xAI custom voice object returned by create,
        read, and update operations. xAI-internal fields (team IDs, consent
        state) are excluded.
      required:
        - voice_id
      properties:
        voice_id:
          type: string
          pattern: ^[a-z0-9]{8}$
        name:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        accent:
          type: string
          nullable: true
        age:
          type: string
          nullable: true
        language:
          type: string
          nullable: true
        use_case:
          type: string
          nullable: true
        tone:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your AI Reserve API key (aireserve_api_…) from the API Keys page in the
        portal (https://portal.aireserve.com/keys).

````