Voice element#

Type: object

Creates a voiceover element by converting the provided text into synthesized speech. The text to be spoken is specified using the text property. The voice property determines the voice to use, and the model property selects the text-to-speech provider (azure or elevenlabs). Optionally, connection chooses your own ElevenLabs API key for the voice.

Important note: Text-to-speech voiceovers may be used only for lawful narration and authorized content. Users may not use voice features for impersonation, deception, fraud, unauthorized voice cloning, celebrity imitation, harassment, adult content, or any use that violates third-party rights or provider terms.

Working with the Voice element#

The Voice element produces a text-to-speech voiceover for your video. Currently supported TTS providers are Microsoft Azure (default, included in every plan) and ElevenLabs.

Note The azure model is the default model and will be used if no model is specified.

Note The voice property is optional too. When it is omitted, each model falls back to its own default voice: en-US-EmmaMultilingualNeural for azure, and vlS1ohKzOkKzVrkOUAOG (Holly) for the elevenlabs models.

Note A voice element whose text is an empty string is ignored: it is dropped from the movie instead of failing the render. If the element also has an explicit duration, that slot is kept as silence so the scene keeps the length you gave it.

Example

This example creates a voiceover for a video using the Azure model.

{
  "resolution": "full-hd",
  "scenes": [
    {
      "elements": [
        {
          "type": "voice",
          "text": "Hello, world!",
          "voice": "en-US-EmmaMultilingualNeural",
          "model": "azure"
        }
      ]
    }
  ]
}

Voice generation costs#

Generating a voiceover may consume credits depending on the model you choose. The exact per-minute cost for each voice model is summarised in Credit consumption. The azure default is included in all plans and does not consume credits.

Voiceovers are cached to avoid calling the upstream provider for the same voiceover multiple times. If you call the API with the same parameters for the same voiceover again, the cached version is reused, avoiding unnecessary costs. To regenerate a voiceover, set the cache property to false.

Using your own ElevenLabs API key#

If you have an ElevenLabs account, you can generate your ElevenLabs voices with your own API key: the voices of your ElevenLabs account become available, and the usage is billed to your ElevenLabs account.

1. Add your key in Dashboard → Connections (API providers tab). See Connections.
2. Star it (★) to use it for every ElevenLabs voice, or reference it in a voice element with connection.

The connection property below explains how the key is chosen, with examples.

Choosing the right voice#

Finding the right voice for your project can be a challenge.

Azure voices#

Azure voices have this format: en-US-EmmaMultilingualNeural.

The first part is the language code (2 digits), the second part is the country code (2 digits) and the third part is the name of the voice.

Browse the complete catalog of Azure voices supported by JSON2Video, organised by language, at json2video.com/ai-voices/azure/languages/. Each voice page lists the exact short name to put in the voice property, plus an audio sample.

ElevenLabs voices#

ElevenLabs voices have natural names like Daniel, Serena, Antoni, Bella, Nova, Shimmer and more. You can also use the ElevenLabs voice ID to specify the voice you want to use.

Browse the complete catalog of ElevenLabs voices supported by JSON2Video, organised by language, at json2video.com/ai-voices/elevenlabs/languages/. Each voice page lists the name and voice ID to put in the voice property, plus an audio sample.

Cloned or custom voices are the exception: they only exist in your own ElevenLabs account, so they will not appear in the catalog above. Use your own ElevenLabs key (see connection) and take the voice ID from your ElevenLabs account.

Properties#

The following properties are required:

• text
• type

cache#

If true, the system will attempt to retrieve and use a previously rendered (cached) version of this element, if an identical version is available. This can significantly reduce processing time. If false, a new render of the element will always be performed, regardless of whether a cached version exists. The default value is true.

comment#

A field for adding descriptive notes or internal memos related to the element. This comment is for your reference and does not affect the rendering process. It can be used to keep notes about the element like describing the content or the purpose of the element.

condition#

A string containing an expression that determines whether the element will be rendered. The element is rendered only if the condition evaluates to true. If the condition is false or an empty string, the element will be skipped and not included in the scene or movie.

connection#

Chooses which API key generates the voice: your own ElevenLabs key, saved in Dashboard → Connections, or JSON2Video's key.

The default key is used for ElevenLabs voice models only: a voice with "model": "azure" (the default model) and no connection uses JSON2Video's key. Automatic subtitles always use JSON2Video's key.

Using your default key. No connection needed: once a key is starred, this voice is generated with it.

{
  "type": "voice",
  "model": "elevenlabs",
  "voice": "Daniel",
  "text": "Hello, world!"
}

Choosing a key by its ID. Useful when you have several ElevenLabs keys, for example one per customer.

{
  "type": "voice",
  "model": "elevenlabs",
  "voice": "Daniel",
  "text": "Hello, world!",
  "connection": "elevenlabs-acme"
}

Using JSON2Video's key in one render, even though you have a default key:

{
  "type": "voice",
  "model": "elevenlabs",
  "voice": "Daniel",
  "text": "Hello, world!",
  "connection": "none"
}

Billing. A voice generated with your own key is billed to your ElevenLabs account and consumes no JSON2Video credits for the voice. JSON2Video never retries a failed voice with its own key.

Voices. With your own key, voice can be:

• a voice name or voice ID from the JSON2Video ElevenLabs catalog (names are not case-sensitive), including catalog voices that are not available with JSON2Video's key; or
• any voice ID from your ElevenLabs account, such as a cloned or library voice.

With JSON2Video's key, only the voices of the catalog are available.

Errors. When a voice fails on your own key, the render fails with a message that says whether the voice or the key is the problem (it never falls back to JSON2Video's key):

Other ElevenLabs errors are shown as ElevenLabs reports them. See Errors.

duration#

Defines the duration of the element in seconds. Use a positive value to specify the element's length. A value of -1 instructs the system to automatically set the duration based on the intrinsic length of the asset or file used by the element. A value of -2 sets the element's duration to match that of its parent scene (if it's inside a scene) or the movie (if it's in the movie elements array).

extra-time#

The amount of time, in seconds, to extend the element's duration beyond its natural length. This allows the element to linger on screen after its content has finished playing or displaying. For example, setting extra-time to 0.5 will keep the element visible for an additional half-second.

fade-in#

The duration, in seconds, of the fade-in effect applied to the element's appearance. A value of 0 means no fade-in effect. Larger values result in a longer fade-in duration. The value must be a non-negative number.

fade-out#

The duration, in seconds, of the fade-out effect applied to the element's disappearance. A value of 0 means no fade-out effect. Larger values result in a longer fade-out duration. The value must be a non-negative number.

id#

A unique identifier for the element within the movie. This string allows you to reference and manage individual elements. If not provided, the system will automatically generate a random string.

model#

The text-to-speech provider to use for synthesizing the voice. elevenlabs is an alias of elevenlabs-v2. Be aware that some models may consume credits for each request.

muted#

If true, the audio track of the element (e.g., a video or audio file) will be muted, effectively silencing it. If false or omitted, the audio will play according to its original volume or the volume setting.

speed#

Sets the playback speed of the synthesized voice. A value of 1 is normal speed, values greater than 1 play faster (e.g. 1.5 is 50% faster, 2 is double speed) and values lower than 1 play slower (e.g. 0.5 is half speed). The voice tempo is changed while preserving its pitch, so it does not sound higher or lower. Because the voice audio is generated first and then sped up, any subtitles generated from it stay in sync. Changing the speed shortens or lengthens the element accordingly. The acceptable range is from 0.5 to 4.

start#

The element's start time, in seconds, determines when it begins playing within its container's timeline. This time is relative to the beginning of the scene it's in or, if the element is part of the movie's elements array, relative to the beginning of the movie itself. The default value is 0, meaning the element starts at the beginning of its container's timeline.

text#

The text content to be synthesized into speech.

type#

This field specifies the element's type and must be set to voice for voiceover elements.

variables#

Defines local variables specific to this element. These variables can be used to dynamically alter the element's properties or content during the rendering process. Variable names must consist of only letters, numbers, and underscores.

voice#

The name of the voice to be used for text-to-speech synthesis. This value determines which voice will be used to generate the audio. Refer to the available voices documentation to explore the supported options.

volume#

Controls the volume gain of the audio track (e.g., a video or audio file). This is a multiplier applied to the original audio level. A value of 1 represents the original volume (no gain), values greater than 1 increase the volume, and values less than 1 decrease the volume. The acceptable range is from 0 to 10. For background music with voiceovers, a usual value is 0.2. Increasing the volume of the audio track can reduce the quality of the audio.

z-index#

Element's z-index, determining its stacking order within the video. Higher values bring the element to the front, obscuring elements with lower values. Lower values send the element to the back, potentially behind other elements. The value must be an integer between -99 and 99; the default is 0. The natural way of layering elements is by the order of the elements in the elements array. If by any reason this does not work in your case, you can use the z-index property to manually control the stacking order.