> ## Documentation Index > Fetch the complete documentation index at: https://anam.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # create voice import > 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 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 by provider voice ID 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 such a request does not reuse an existing Voice. Two ElevenLabs options reach voices Anam's own ElevenLabs account can't. `useOrganizationKey: true` validates and speaks with your organization's saved ElevenLabs API key (PUT /v1/voices/elevenlabs-key), so any voice in your own ElevenLabs account works, including instant clones, Voice Design voices and Professional Voice Clones; these voices have `isZdr: false`. `shareUrl` instead of `provider` and `providerVoiceId` imports a Professional Voice Clone shared with Anyone with the link, which then speaks with Anam's account. A share link for a voice your organization already has on the requested model regenerates its preview, applies any displayName, and returns that Voice with 200 instead of creating another. ## OpenAPI ````yaml https://api.anam.ai/swagger.json post /v1/voice-imports openapi: 3.1.0 info: title: Anam AI API version: '1.0' servers: - url: https://api.anam.ai description: Anam API security: - BearerAuth: [] tags: - name: Sessions - name: Avatar Videos - name: Meetings - name: Personas - name: Avatars - name: Voices - name: Pronunciation Dictionaries - name: LLMs - name: Knowledge - name: Tools - name: Share Links - name: Engine paths: /v1/voice-imports: post: tags: - Voices summary: Validate and import a provider voice description: >- 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 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 by provider voice ID 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 such a request does not reuse an existing Voice. Two ElevenLabs options reach voices Anam's own ElevenLabs account can't. `useOrganizationKey: true` validates and speaks with your organization's saved ElevenLabs API key (PUT /v1/voices/elevenlabs-key), so any voice in your own ElevenLabs account works, including instant clones, Voice Design voices and Professional Voice Clones; these voices have `isZdr: false`. `shareUrl` instead of `provider` and `providerVoiceId` imports a Professional Voice Clone shared with Anyone with the link, which then speaks with Anam's account. A share link for a voice your organization already has on the requested model regenerates its preview, applies any displayName, and returns that Voice with 200 instead of creating another. operationId: createVoiceImport requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreateVoiceImportRequest' - $ref: '#/components/schemas/CreateShareLinkVoiceImportRequest' examples: default: $ref: '#/components/examples/VoiceImportRequest' ownKey: $ref: '#/components/examples/VoiceImportOwnKeyRequest' shareLink: $ref: '#/components/examples/VoiceImportShareLinkRequest' responses: '200': description: >- A share link for a voice the organization already has on this model; its preview was regenerated and any displayName applied. content: application/json: schema: $ref: '#/components/schemas/Voice' '201': description: The validated Voice was created. headers: Location: schema: type: string description: Relative URL of the created Voice resource. content: application/json: schema: $ref: '#/components/schemas/Voice' examples: default: $ref: '#/components/examples/VoiceResponse' '400': description: >- Invalid request (`invalid_request`), unsupported provider or model (`invalid_provider_details`), the provider refused this voice with this model (`provider_rejected`), or `shareUrl` isn't a well-formed ElevenLabs share link (`invalid_share_link`). content: application/json: schema: $ref: '#/components/schemas/VoiceImportApiError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/VoiceImportApiError' '403': description: >- API key lacks voice write access, or the option isn't enabled for this organization (`organization_key_unavailable` for `useOrganizationKey`, `share_link_unavailable` for `shareUrl`). content: application/json: schema: $ref: '#/components/schemas/VoiceImportApiError' '409': description: >- ElevenLabs attachment conflict (`voice_bound_elsewhere`), another attachment is running (`import_in_progress`, retryable), or `useOrganizationKey` with no saved key (`organization_key_missing`). content: application/json: schema: $ref: '#/components/schemas/VoiceImportApiError' examples: voiceBoundElsewhere: value: code: voice_bound_elsewhere message: >- This ElevenLabs voice is linked to another organization. Contact support to use it. requestId: req_123 retryable: false importInProgress: value: code: import_in_progress message: This ElevenLabs voice is being imported. Retry shortly. requestId: req_123 retryable: true '422': description: >- The provider can't find the voice (`voice_not_accessible`): a wrong ID, a private voice Anam isn't allowed to use, or a share link whose voice ElevenLabs can't find, that is no longer shared, or that isn't a Professional Voice Clone. The message names each way that voice type reaches Anam, including `shareUrl` and `useOrganizationKey` where your organization has them. With `useOrganizationKey`, it means your saved key can't reach the voice. ElevenLabs refusing the saved key itself is `organization_key_rejected`. `docsUrl` links to the steps. content: application/json: schema: $ref: '#/components/schemas/VoiceImportApiError' examples: voiceNotAccessible: value: code: voice_not_accessible message: >- Anam's ElevenLabs account can't access voice abc123. A Voice Library voice imports by its voice ID, so check the ID. To import a Professional Voice Clone with Anam's ElevenLabs account, share it by link: send its share link as shareUrl instead of providerVoiceId (in ElevenLabs: Share voice, Anyone with the link); one in your own ElevenLabs account also imports with useOrganizationKey: true. Instant clones and Voice Design voices stay in the ElevenLabs account that made them: add useOrganizationKey: true to import them with your organization's saved ElevenLabs API key, or clone the voice in Anam (POST /v1/voices with audio). requestId: req_123 retryable: false docsUrl: >- https://anam.ai/docs/personas/voices/custom-voices#import-elevenlabs-voices organizationKeyRejected: value: code: organization_key_rejected message: >- ElevenLabs didn't accept your organization's saved API key. Save a new key with Text to Speech access using PUT /v1/voices/elevenlabs-key, then retry the same request. requestId: req_123 retryable: false docsUrl: >- https://anam.ai/docs/personas/voices/custom-voices#import-elevenlabs-voices '429': description: Voice provider rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/VoiceImportApiError' '500': description: Voice import service unavailable content: application/json: schema: $ref: '#/components/schemas/VoiceImportApiError' '502': description: Voice provider or preview storage unavailable content: application/json: schema: $ref: '#/components/schemas/VoiceImportApiError' '504': description: Voice validation timed out content: application/json: schema: $ref: '#/components/schemas/VoiceImportApiError' components: schemas: CreateVoiceImportRequest: type: object description: >- Import a provider voice by its ID. To import an ElevenLabs Professional Voice Clone by its share link, send CreateShareLinkVoiceImportRequest instead. additionalProperties: false required: - provider - providerVoiceId properties: displayName: type: string minLength: 1 maxLength: 191 description: >- Optional name override. Defaults to the provider name (trimmed and limited to 191 characters), or Imported if unavailable. provider: type: string enum: - CARTESIA - ELEVENLABS - FISH_AUDIO providerVoiceId: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_-]+$ description: Voice identifier from the selected provider. providerModelId: type: string enum: - 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_v4_turbo - eleven_v3_conversational - eleven_v4 - eleven_v3 - eleven_flash_v2_5 - eleven_multilingual_v2 - eleven_flash_v2 - eleven_turbo_v2_5 - s2.1-pro - s2-pro - s1 description: >- Supported model for the selected provider. Omit for the provider default. providerConfig: type: object additionalProperties: true sampleUrl: type: string format: uri gender: type: string enum: - MALE - FEMALE - NEUTRAL country: type: string minLength: 2 maxLength: 2 description: type: string description: >- Optional description override. Defaults to provider metadata, or null if unavailable. An explicit empty string is preserved. useOrganizationKey: type: boolean description: >- ELEVENLABS only. Validate and speak with your organization's saved ElevenLabs API key (PUT /v1/voices/elevenlabs-key) instead of Anam's, for a voice in your own ElevenLabs account: an instant clone, a Voice Design voice or a Professional Voice Clone. The voice gets `isZdr: false`, and ElevenLabs bills its speech to the key's account. CreateShareLinkVoiceImportRequest: type: object description: >- Import an ElevenLabs Professional Voice Clone shared with Anyone with the link. The link names the voice, so providerVoiceId and useOrganizationKey are not accepted. The voice speaks with Anam's ElevenLabs account. additionalProperties: false required: - shareUrl properties: shareUrl: type: string format: uri maxLength: 2048 description: >- The link from Share voice in ElevenLabs: https://elevenlabs.io/app/voice-lab/share//. provider: type: string enum: - ELEVENLABS description: Optional; share links are ElevenLabs only. providerModelId: type: string description: ElevenLabs model. Omit for the default, eleven_v3_conversational. displayName: type: string minLength: 1 maxLength: 191 description: Optional name. Defaults to the voice's ElevenLabs name. Voice: type: object description: A voice preset a persona can use for text-to-speech. properties: id: type: string format: uuid description: Unique identifier for the voice. displayName: type: string description: Human-readable name shown in the Lab. provider: type: string enum: - CARTESIA - ELEVENLABS - FISH_AUDIO description: Upstream TTS provider for this voice. providerVoiceId: type: - string - 'null' description: The upstream provider's identifier for the voice. providerModelId: type: - string - 'null' description: The upstream provider's model identifier used to generate speech. sampleUrl: type: - string - 'null' format: uri description: URL of a short audio preview of the voice. previewSampleUrl: type: - string - 'null' format: uri description: Alias for `sampleUrl`, kept for backwards compatibility. gender: type: - string - 'null' enum: - MALE - FEMALE - NEUTRAL - null description: Perceived gender of the voice, if categorised. country: type: - string - 'null' description: ISO 3166-1 alpha-2 country code representing the voice's accent. description: type: - string - 'null' description: Free-form description of the voice's character. displayTags: type: array items: type: string description: Tags used to categorise the voice in the Lab UI. isZdr: type: boolean description: Whether this voice meets the Zero Data Retention requirements. createdByOrganizationId: type: - string - 'null' description: >- 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: type: string format: date-time description: Timestamp when the voice was created. updatedAt: type: string format: date-time description: Timestamp when the voice was last updated. VoiceImportApiError: type: object required: - code - message - requestId - retryable properties: code: type: string description: >- Stable machine-readable failure code. `invalid_request`: the body failed validation (see `details.issues`). `invalid_provider_details`: the provider or model is missing or unsupported. `voice_not_accessible`: the provider can't find the voice for Anam's account, either a wrong ID or a private voice; `message` lists the ways that voice type can reach Anam. `provider_rejected`: the provider refused this voice with this model; try another model. `voice_bound_elsewhere`: the ElevenLabs voice was imported by another organization through its share link. `import_in_progress`: another import of the same ElevenLabs voice is running; retry. `provider_rate_limited`, `provider_unavailable`, `provider_timeout`: provider-side; retry when `retryable` is true. `provider_auth_failed`, `sample_upload_failed`, `internal_error`: Anam-side; retry later or contact support with `requestId`. `organization_key_unavailable`: your organization can't use its own ElevenLabs key; remove `useOrganizationKey` or ask Anam to enable it. `organization_key_missing`: no ElevenLabs key is saved; save one with PUT /v1/voices/elevenlabs-key. `organization_key_rejected`: ElevenLabs refused the saved key; save a new one. `share_link_unavailable`: share-link import isn't enabled for your organization. `invalid_share_link`: `shareUrl` isn't a well-formed ElevenLabs share link; a link whose voice ElevenLabs can't find, that is no longer shared, or that isn't a Professional Voice Clone gets `voice_not_accessible`. `invalid_elevenlabs_key`: ElevenLabs didn't accept the key sent to PUT /v1/voices/elevenlabs-key. `rate_limited`: too many key checks for your organization this hour; retry after an hour. enum: - invalid_request - invalid_provider_details - voice_not_accessible - provider_rejected - voice_bound_elsewhere - import_in_progress - provider_rate_limited - provider_unavailable - provider_timeout - provider_auth_failed - sample_upload_failed - request_cancelled - internal_error - organization_key_unavailable - organization_key_missing - organization_key_rejected - share_link_unavailable - invalid_share_link - invalid_elevenlabs_key - rate_limited message: type: string description: >- What went wrong and what to do about it, written to be shown to a person or acted on by an agent. requestId: type: string description: Quote this when contacting Anam support. retryable: type: boolean description: Whether the same request may succeed if repeated later. docsUrl: type: string format: uri description: >- Documentation that explains the fix. Present on `voice_not_accessible`, the `organization_key_*` codes and the share-link codes. details: type: object additionalProperties: true examples: VoiceImportRequest: summary: Validate and import an existing Cartesia voice value: displayName: Customer support voice provider: CARTESIA providerVoiceId: voice_abc123 providerModelId: sonic-3.6 country: GB VoiceImportOwnKeyRequest: summary: Import a voice from your own ElevenLabs account with your saved key value: provider: ELEVENLABS providerVoiceId: 2sJ00L1aIxJCDJzpy6qQ providerModelId: eleven_v3_conversational useOrganizationKey: true VoiceImportShareLinkRequest: summary: Import an ElevenLabs Professional Voice Clone by its share link value: shareUrl: >- https://elevenlabs.io/app/voice-lab/share/0123456789abcdef0123456789abcdef/AbCdEfGhIjKlMnOpQrSt providerModelId: eleven_v3_conversational displayName: Support lead VoiceResponse: summary: A single voice resource value: id: de23e340-1416-4dd8-977d-065a7ca11697 displayName: Lucy - Fresh & Casual provider: ELEVENLABS providerVoiceId: lcMyyd2HUfFzxdCaC4Ta providerModelId: eleven_flash_v2_5 sampleUrl: >- https://newgxnc1uqs0jnqm.public.blob.vercel-storage.com/voice-samples/de23e340-1416-4dd8-977d-065a7ca11697/1760617899390.mp3 previewSampleUrl: >- https://newgxnc1uqs0jnqm.public.blob.vercel-storage.com/voice-samples/de23e340-1416-4dd8-977d-065a7ca11697/1760617899390.mp3 gender: FEMALE country: GB description: >- Energetic and youthful British voice, perfect for narrations and conversational agents. displayTags: - fast isZdr: true createdByOrganizationId: null createdAt: '2026-04-20T10:00:00.000Z' updatedAt: '2026-04-20T10:00:00.000Z' securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.