---
title: "Validate and import a provider voice"
method: POST
path: "/v1/voice-imports"
tags: ["Voices"]
---

# Validate and import a provider voice

`POST /v1/voice-imports`

Synchronously validates the provider voice/model and persists the Voice only after a real TTS preview succeeds. A provider validation may take up to 90 seconds, after a best-effort metadata lookup of up to 5 seconds; the first import of an ElevenLabs Voice Library voice typically takes about a minute while ElevenLabs adds it to Anam's account. Only provider and providerVoiceId are required. Omitted displayName and description use provider metadata; supplied values take precedence. If unavailable, the name is Imported <providerVoiceId> and the description is null. This endpoint does not accept voice-clone audio; use POST /v1/voices for cloning. No Idempotency-Key is required. Every successful request creates a new Voice, even when the same provider voice ID and model already exist in the organization. Omitted models resolve to the provider default. Repeating a request does not reuse an existing Voice.

## Request body

- CreateVoiceImportRequest
  - `displayName` string — Optional name override. Defaults to the provider name (trimmed and limited to 191 characters), or Imported <providerVoiceId> if unavailable.
  - `provider` 'CARTESIA' | 'ELEVENLABS' | 'FISH_AUDIO', required
  - `providerVoiceId` string, required — Voice identifier from the selected provider.
  - `providerModelId` 'sonic-3.6' | 'sonic-3.6-2026-08-27' | 'sonic-3.5' | 'sonic-3.5-2026-05-04' | 'sonic-3' | 'sonic-3-2026-01-12' | 'sonic-2' | 'sonic-latest' | 'eleven_flash_v2_5' | 'eleven_flash_v2' | 'eleven_multilingual_v2' | 'eleven_turbo_v2_5' | 'eleven_v3' | 'eleven_v3_conversational' | 'eleven_v4' | 'eleven_v4_turbo' | 's2.1-pro' | 's2-pro' | 's1' — Supported model for the selected provider. Omit for the provider default.
  - `providerConfig` object
  - `sampleUrl` string, uri
  - `gender` 'MALE' | 'FEMALE' | 'NEUTRAL'
  - `country` string
  - `description` string — Optional description override. Defaults to provider metadata, or null if unavailable. An explicit empty string is preserved.

## Response `201`

The validated Voice was created.

- Voice — A voice preset a persona can use for text-to-speech.
  - `id` string, uuid — Unique identifier for the voice.
  - `displayName` string — Human-readable name shown in the Lab.
  - `provider` 'CARTESIA' | 'ELEVENLABS' | 'FISH_AUDIO' — Upstream TTS provider for this voice.
  - `providerVoiceId` string, nullable — The upstream provider's identifier for the voice.
  - `providerModelId` string, nullable — The upstream provider's model identifier used to generate speech.
  - `sampleUrl` string, uri, nullable — URL of a short audio preview of the voice.
  - `previewSampleUrl` string, uri, nullable — Alias for `sampleUrl`, kept for backwards compatibility.
  - `gender` 'MALE' | 'FEMALE' | 'NEUTRAL' | 'null', nullable — Perceived gender of the voice, if categorised.
  - `country` string, nullable — ISO 3166-1 alpha-2 country code representing the voice's accent.
  - `description` string, nullable — Free-form description of the voice's character.
  - `displayTags` string[] — Tags used to categorise the voice in the Lab UI.
  - `isZdr` boolean — Whether this voice meets the Zero Data Retention requirements.
  - `createdByOrganizationId` string, nullable — ID of the organization that created the voice, or `null` for stock voices. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created.
  - `createdAt` string, date-time — Timestamp when the voice was created.
  - `updatedAt` string, date-time — Timestamp when the voice was last updated.

## Other responses

- `400` — Invalid request or unsupported provider/model
- `401` — Missing or invalid API key
- `403` — API key lacks voice write access
- `429` — Voice provider rate limit exceeded
- `500` — Voice import service unavailable
- `502` — Voice provider or preview storage unavailable
- `504` — Voice validation timed out

## Changes

- **2026-10-07** `bb35a5087dd6` — 2 info
  - added the new `eleven_v4` enum value to the request property `providerModelId`
  - added the new `eleven_v4_turbo` enum value to the request property `providerModelId`
- **2026-09-26** `dc7e31f03c66` — 1 breaking, 1 info
  - removed the enum value `OPENAI_ADVANCED_VOICE` of the request property `provider`
  - removed the `OPENAI_ADVANCED_VOICE` enum value from the `provider` response property for the response status `201`
- **2026-09-19** `f4d1a1caad42` — 1 info
  - added the new `sonic-3.6-2026-08-27` enum value to the request property `providerModelId`
- **2026-09-18** `450b7bc2c11f` — 2 info
  - added the new `eleven_v3` enum value to the request property `providerModelId`
  - added the new `eleven_v3_conversational` enum value to the request property `providerModelId`
- **2026-09-15** `c89509d87918` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/anam/apis/anam-ai-api/changes/v1/voice-imports/post.md)

---

[API](https://skmtc.dev/anam/apis/anam-ai-api.md) · [All operations](https://skmtc.dev/anam/apis/anam-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/anam/apis/anam-ai-api/revisions/bb35a5087dd6?raw)