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

# Update Voice

> Update the name, description, gender, and accent of a voice. To set the gender back to the default, set the gender to `null`. If gender is not specified, the gender will not be updated.



## OpenAPI

````yaml latest.yml PATCH /voices/{id}
openapi: 3.0.1
info:
  title: Cartesia API
  version: 0.0.1
servers:
  - url: https://api.cartesia.ai
    description: Production
security: []
paths:
  /voices/{id}:
    patch:
      tags:
        - Voices
      summary: Update Voice
      description: >-
        Update the name, description, gender, and accent of a voice. To set the
        gender back to the default, set the gender to `null`. If gender is not
        specified, the gender will not be updated.
      operationId: voices_update
      parameters:
        - $ref: '#/components/parameters/CartesiaVersionHeader'
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/VoiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVoiceRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Voice'
      security:
        - APIKeyAuth: []
components:
  parameters:
    CartesiaVersionHeader:
      name: Cartesia-Version
      in: header
      description: API version header.
      required: true
      schema:
        type: string
        format: date
        example: '2026-08-14'
        default: '2026-08-14'
        enum:
          - '2026-08-14'
  schemas:
    VoiceId:
      title: VoiceId
      type: string
      description: >-
        The ID of the voice. Find one in the [Voice
        Library](https://play.cartesia.ai/voices) or via [List
        Voices](/api-reference/voices/list).
    UpdateVoiceRequest:
      title: UpdateVoiceRequest
      type: object
      properties:
        name:
          type: string
          description: The name of the voice.
        tagline:
          type: string
          description: A few words describing the voice. At most 32 characters.
          minimum: 0
          maximum: 32
        description:
          type: string
          description: >-
            A description for the voice, typically longer than the tagline if
            both are provided.
        gender:
          $ref: '#/components/schemas/GenderPresentation'
          nullable: true
        accent:
          allOf:
            - $ref: '#/components/schemas/VoiceAccent'
          nullable: true
          description: >-
            Catalog accent id from GET /accents (e.g. `southern-us`). Display
            names are rejected.
        access:
          description: >-
            Controls who can access this resource. Prefer `"public"` |
            `"private"`. Deprecated nested `{ "type": "public" | "private" }` is
            still accepted.
          oneOf:
            - type: string
              enum:
                - private
                - public
              description: >-
                Set to `"public"` to let any Cartesia user with the resource ID
                use it, or `"private"` to restrict it to your organization.
            - type: object
              deprecated: true
              description: >-
                Deprecated. Prefer a top-level `access` string (`"public"` |
                `"private"`).
              properties:
                type:
                  type: string
                  enum:
                    - private
                    - public
                  description: >-
                    Set to `"public"` to let any Cartesia user with the resource
                    ID use it, or `"private"` to restrict it to your
                    organization.
              required:
                - type
    Voice:
      title: Voice
      type: object
      properties:
        id:
          $ref: '#/components/schemas/VoiceId'
        is_owner:
          type: boolean
          description: Whether your organization owns the voice.
        access:
          type: string
          enum:
            - private
            - public
          description: >-
            Who can use the resource. `private` means only the owner can use the
            resource. `public` means everyone can use the resource.
        name:
          type: string
          description: The display name of the voice. Does not include the tagline.
        tagline:
          type: string
          description: >-
            A short descriptor for the voice (at most 32 characters). Empty
            string when unset.
          default: ''
          maximum: 32
        description:
          type: string
          description: >-
            A description for the voice, typically longer than the tagline if
            both are provided.
        gender:
          $ref: '#/components/schemas/GenderPresentation'
          nullable: true
          description: The gender of the voice, if specified.
        accent:
          allOf:
            - $ref: '#/components/schemas/VoiceAccent'
          nullable: true
          description: >-
            Catalog accent id from GET /accents (e.g. `southern-us`). Display
            names are not returned on this API version.
        created_at:
          type: string
          format: date-time
          description: The date and time the voice was created.
        preview_file_url:
          type: string
          nullable: true
          description: >-
            A URL to download a preview audio file for this voice. Useful to
            avoid consuming credits when looking for the right voice. The URL
            requires the same Authorization header. Voice previews may be
            changed, moved, or deleted so you should avoid storing the URL
            permanently. This property will be null if there's no preview
            available. Only included when `expand[]` includes
            `preview_file_url`.
        language:
          $ref: '#/components/schemas/VoiceLanguage'
          deprecated: true
          description: >-
            Deprecated. Prefer `locales[].locale` (BCP-47). ISO 639-1 language
            code (e.g. `en`, `fr`, `zh`).
        locales:
          type: array
          description: >-
            Locales this voice can speak. The native/source locale is first
            (`is_native: true`), followed by attached cross-lingual locales.
            Locale codes are BCP-47 language-region tags (for example `en-US`,
            `es-MX`).
          items:
            type: object
            properties:
              locale:
                type: string
                pattern: ^[a-z]{2}-[A-Z]{2}$
                description: The locale's BCP-47 language-region tag (e.g. `en-US`).
              is_native:
                type: boolean
                description: Whether this is the voice's native/source locale.
            required:
              - locale
              - is_native
          example:
            - locale: en-US
              is_native: true
            - locale: es-MX
              is_native: false
        country:
          $ref: '#/components/schemas/VoiceCountry'
          nullable: true
          description: >-
            Deprecated. Prefer `locales[].locale` (BCP-47). ISO 3166-1 alpha-2
            country code when available (e.g. `US`, `GB`, `FR`).
          deprecated: true
        is_pro:
          type: boolean
          description: Whether this voice is a pro voice clone.
        visibility:
          type: string
          enum:
            - owner
            - all
          description: >-
            When the resource is returned by the list endpoint. `owner` means
            the resource appears for the owner only. `all` means the resource
            appears for all users.
      required:
        - id
        - is_owner
        - access
        - visibility
        - name
        - tagline
        - description
        - created_at
        - language
        - locales
      example:
        id: db6b0ed5-d5d3-463d-ae85-518a07d3c2b4
        is_owner: false
        access: public
        name: Skylar
        tagline: Friendly Guide
        description: Approachable American female ideal for customer care and support.
        gender: feminine
        accent: general-american
        language: en
        locales:
          - locale: en-US
            is_native: true
          - locale: hi-IN
            is_native: false
          - locale: es-MX
            is_native: false
          - locale: de-DE
            is_native: false
          - locale: he-IL
            is_native: false
          - locale: it-IT
            is_native: false
          - locale: pt-BR
            is_native: false
          - locale: ta-IN
            is_native: false
        country: US
        created_at: '2026-03-31T17:37:05.961874Z'
        visibility: all
    GenderPresentation:
      title: GenderPresentation
      type: string
      enum:
        - masculine
        - feminine
        - gender_neutral
    VoiceAccent:
      title: VoiceAccent
      description: >-
        Catalog accent id from GET /accents (for example `southern-us` or
        `parisian`). Must be valid for the voice's `language`. Display names are
        rejected on this API version.
      oneOf:
        - title: Arabic
          description: Only available when language is Arabic (`ar`).
          type: string
          enum:
            - arabic
            - khaleeji
            - middle-eastern-arabic
            - modern-standard-arabic
        - title: Bengali
          description: Only available when language is Bengali (`bn`).
          type: string
          enum:
            - jessore
        - title: Bulgarian
          description: Only available when language is Bulgarian (`bg`).
          type: string
          enum:
            - bulgarian
        - title: Chinese
          description: Only available when language is Chinese (`zh`).
          type: string
          enum:
            - mandarin
            - taiwanese-mandarin
        - title: Croatian
          description: Only available when language is Croatian (`hr`).
          type: string
          enum:
            - zagreb
        - title: Czech
          description: Only available when language is Czech (`cs`).
          type: string
          enum:
            - czech
        - title: Danish
          description: Only available when language is Danish (`da`).
          type: string
          enum:
            - danish
        - title: Dutch
          description: Only available when language is Dutch (`nl`).
          type: string
          enum:
            - randstad
        - title: English
          description: Only available when language is English (`en`).
          type: string
          enum:
            - african-american
            - arabic-english
            - australian
            - british
            - california
            - canadian-english
            - general-american
            - indian-english
            - irish
            - midwestern-american
            - new-york
            - new-zealand
            - singaporean
            - south-african
            - southern-us
        - title: Finnish
          description: Only available when language is Finnish (`fi`).
          type: string
          enum:
            - finnish
        - title: French
          description: Only available when language is French (`fr`).
          type: string
          enum:
            - african-french
            - belgian-french
            - canadian-french
            - parisian
        - title: Georgian
          description: Only available when language is Georgian (`ka`).
          type: string
          enum:
            - tbilisi
        - title: German
          description: Only available when language is German (`de`).
          type: string
          enum:
            - high-german
            - swiss-standard
        - title: Greek
          description: Only available when language is Greek (`el`).
          type: string
          enum:
            - thessaloniki
        - title: Gujarati
          description: Only available when language is Gujarati (`gu`).
          type: string
          enum:
            - parsi
        - title: Hebrew
          description: Only available when language is Hebrew (`he`).
          type: string
          enum:
            - israeli
        - title: Hindi
          description: Only available when language is Hindi (`hi`).
          type: string
          enum:
            - bagheli
            - hindi
        - title: Hungarian
          description: Only available when language is Hungarian (`hu`).
          type: string
          enum:
            - budapest
        - title: Indonesian
          description: Only available when language is Indonesian (`id`).
          type: string
          enum:
            - jakarta
        - title: Italian
          description: Only available when language is Italian (`it`).
          type: string
          enum:
            - abruzzo-italian
            - campania
            - italian
        - title: Japanese
          description: Only available when language is Japanese (`ja`).
          type: string
          enum:
            - japanese
            - standard-japanese
        - title: Kannada
          description: Only available when language is Kannada (`kn`).
          type: string
          enum:
            - southern-karnataka
        - title: Korean
          description: Only available when language is Korean (`ko`).
          type: string
          enum:
            - korean
        - title: Malay
          description: Only available when language is Malay (`ms`).
          type: string
          enum:
            - malay
        - title: Malayalam
          description: Only available when language is Malayalam (`ml`).
          type: string
          enum:
            - north-kerala
        - title: Marathi
          description: Only available when language is Marathi (`mr`).
          type: string
          enum:
            - konkani
        - title: Norwegian
          description: Only available when language is Norwegian (`no`).
          type: string
          enum:
            - oslo
        - title: Odia
          description: Only available when language is Odia (`or`).
          type: string
          enum:
            - odia
        - title: Polish
          description: Only available when language is Polish (`pl`).
          type: string
          enum:
            - polish
        - title: Portuguese
          description: Only available when language is Portuguese (`pt`).
          type: string
          enum:
            - brazilian-portuguese
            - european-portuguese
        - title: Punjabi
          description: Only available when language is Punjabi (`pa`).
          type: string
          enum:
            - powadhi
        - title: Romanian
          description: Only available when language is Romanian (`ro`).
          type: string
          enum:
            - moldovan
            - romanian
        - title: Russian
          description: Only available when language is Russian (`ru`).
          type: string
          enum:
            - russian
        - title: Slovak
          description: Only available when language is Slovak (`sk`).
          type: string
          enum:
            - slovak
        - title: Spanish
          description: Only available when language is Spanish (`es`).
          type: string
          enum:
            - camba
            - castilian
            - chilean
            - colombian
            - mexican
            - peruvian
        - title: Swedish
          description: Only available when language is Swedish (`sv`).
          type: string
          enum:
            - stockholm
        - title: Tagalog
          description: Only available when language is Tagalog (`tl`).
          type: string
          enum:
            - manila
        - title: Tamil
          description: Only available when language is Tamil (`ta`).
          type: string
          enum:
            - central-tamil
        - title: Telugu
          description: Only available when language is Telugu (`te`).
          type: string
          enum:
            - telangana
        - title: Thai
          description: Only available when language is Thai (`th`).
          type: string
          enum:
            - central-thai
        - title: Turkish
          description: Only available when language is Turkish (`tr`).
          type: string
          enum:
            - istanbul
        - title: Ukrainian
          description: Only available when language is Ukrainian (`uk`).
          type: string
          enum:
            - kyiv
        - title: Urdu
          description: Only available when language is Urdu (`ur`).
          type: string
          enum:
            - indian-urdu
            - urdu
        - title: Vietnamese
          description: Only available when language is Vietnamese (`vi`).
          type: string
          enum:
            - central-vietnamese
            - southern-vietnamese
    VoiceLanguage:
      type: string
      description: The voice's language, as an ISO 639-1 code (e.g. `en`, `fr`, `zh`)
      example: en
    VoiceCountry:
      title: VoiceCountry
      type: string
      description: >-
        The country associated with the voice, as an ISO 3166-1 alpha-2 code
        when available (e.g. `US`, `GB`, `FR`).
      example: US
  securitySchemes:
    APIKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Cartesia API key (`sk_car_...`). Get one at
        [play.cartesia.ai/keys](https://play.cartesia.ai/keys).
      x-default: $CARTESIA_API_KEY

````