Connections#

A connection is a set of credentials you save once in the dashboard and use by its ID. The secret part (an API key, a password or a secret access key) is stored encrypted and never appears in your movie JSON or in API requests.

Connections live at json2video.com/dashboard/connections. The page has two tabs:

Keys for your JSON2Video account are a different thing: they live under API keys.

Managing connections requires the Manager role. Every plan can add connections.

API providers#

ElevenLabs keys#

Use your own ElevenLabs API key when you want voices generated with your ElevenLabs account: the voices of your account (cloned, designed or library voices) become available, and the usage is billed to your ElevenLabs account instead of running on JSON2Video's key.

All your ElevenLabs keys are listed in one table:

Each row has a Test button and a menu with Replace key, Copy JSON snippet ("connection": "<id>") and Remove.

Add a key#

1. Create an API key in your ElevenLabs account (profile menu → API Keys). Give it at least Text to Speech access.
2. In API providers, click Add key on the ElevenLabs card.
3. Keep the suggested ID (elevenlabs, then elevenlabs-2, …) or type your own. See Connection IDs.
4. Paste the key. ElevenLabs keys start with sk_: the dialog does not let you save a key that doesn't.
5. Optionally click Test key, then Save key.

If you have no default key yet, the key you add becomes your default (★) — the dialog tells you so before you save. If you already have a default, the new key is saved without a star.

The default key (★)#

The starred key is used for every ElevenLabs voice that has no connection, in every render. You can have one default key.

• Click the empty star of a key to make it the default. When you have no default yet, the dashboard asks you to confirm, because from then on your voices are billed to your ElevenLabs account.
• Click the star of another key to move the default there (no confirmation).
• Click the filled star to remove it. Voices without connection go back to JSON2Video's key.

Which key a voice element uses:

The default key applies to voice elements only. Automatic subtitles are unaffected. See the voice element's connection property for examples and error messages.

Test and Status#

Test asks ElevenLabs whether it accepts the key. Nothing is generated and nothing is billed. The result is saved as the key's Status:

A test never blocks saving or using a key. Replacing a key resets its Status to Not tested.

Replace or remove a key#

• Replace key stores a new key under the same ID. Renders that use this connection switch to the new key; its ID, star and "Last used" stay.
• Remove deletes the key. Renders that reference "connection": "<id>" will fail. If it was your default key, voices without connection use JSON2Video's key again.

Other keys#

Keys saved before this page existed, whose ID does not tell us which service they belong to, are listed under Other keys. They are never used as a default, but they keep working in renders that reference them with connection.

• This is an ElevenLabs key moves the key to the ElevenLabs table (without a star).
• Remove deletes it.

Keys whose ID mentions ElevenLabs (for example my-elevenlabs-connection) are already shown in the ElevenLabs table, without a star.

Output destinations#

An output destination is where JSON2Video delivers a rendered video. You can create as many as you need of each type:

Add a destination#

Click Add destination and pick Webhook, FTP, SFTP or Amazon S3.

The folder and file name of FTP, SFTP and Amazon S3 destinations accept these macros:

For Amazon S3, the dialog also shows the Minimal IAM policy for the bucket and folder you typed, with a copy button: attach it to the IAM user whose key you use. See Amazon S3 delivery for the whole setup in AWS.

Webhooks saved before this page existed that use http:// keep receiving your renders; the list shows a warning next to them, and you need an https:// URL to change the URL.

Use a destination in a movie#

Reference the destination by its ID. Copy JSON in the row menu copies this snippet:

{
  "exports": [
    {
      "destinations": [
        { "id": "my-sftp" }
      ]
    }
  ]
}

For an Amazon S3 destination, the snippet also names the type: { "type": "aws-s3", "id": "my-s3" }.

Fields you add next to id override the saved ones for that render. For example, this uses the saved host and login of my-sftp but writes to another folder:

{
  "exports": [
    {
      "destinations": [
        { "id": "my-sftp", "remote-path": "/customers/acme/__yyyy__/" }
      ]
    }
  ]
}

An Amazon S3 destination accepts only remote-path and file next to id: the bucket, the region and the keys always come from the saved destination. Never put AWS keys in a movie — POST /v2/movies refuses it with the code aws_keys_in_movie. See Amazon S3 delivery.

Test a destination#

Use Test destination in the form (before or after saving — nothing is saved by a test), or Test in the row menu.

• Webhook: JSON2Video sends one POST request shaped like a real delivery, with fake values and "test": true. It really reaches your receiver, so an automation behind it runs once with the test data. The test waits up to 10 seconds for an answer (real deliveries wait 30 seconds).
• FTP / SFTP: JSON2Video connects, logs in and lists the remote folder — only the part of the folder before its first macro, because macro folders are created by the delivery. Nothing is uploaded.
• Amazon S3: JSON2Video writes a small file, json2video-test.txt, to the part of the folder before its first macro, and leaves it there: JSON2Video never deletes it. A new test overwrites it. Nothing is listed, read or deleted. See The test file.

When you edit a destination, the test uses your unsaved changes; an empty password or secret access key field uses the stored one.

Last delivery#

The Last delivery column shows whether the last render that used the destination delivered (Delivered) or not (Failed), and when. Hover over it to see the error. A dash means no delivery has been recorded yet.

The result of every delivery of a render is also shown in Render logs → the render → Deliveries, and returned as destinations_result by GET /v2/movies.

Test limit#

You can run up to 20 tests per hour (ElevenLabs keys and destinations together, counted per clock hour in UTC). After that, Test answers You can run up to 20 tests per hour. Try again after HH:MM UTC. Tests that are refused before anything is contacted (for example, a form error) do not count.

Connection IDs#

IDs of new connections must:

• be 1–64 characters long, using lowercase letters, numbers, - and _, starting with a letter or a number;
• not be none (reserved: "connection": "none" means "JSON2Video's key");
• not be a URL;
• not look like a secret.

Never put a key or a password in an ID. IDs are not encrypted: they appear in the dashboard, in logs and in your movie JSON. If an existing connection's ID looks like a secret, the dashboard shows a warning next to it: create a new connection with a plain name, update your movies, and delete the old one.

Existing connections keep their IDs, even if they don't follow these rules. IDs are used exactly as saved, so match the case and spelling in your movie JSON.

Security notes#

• Keys, passwords and secret access keys are stored encrypted and are never shown again — only the last 4 characters of an API key.
• JSON2Video only connects to public internet addresses. A webhook, FTP or SFTP host that resolves to a private, loopback, link-local or reserved address is refused, both in tests and in deliveries.
• AWS keys are never accepted in a movie JSON, only in a saved Amazon S3 destination.
• Removing a connection is immediate. Renders that still reference its ID fail (voices) or record a failed delivery (destinations).

See also#

• Voice element — connection
• ElevenLabs integration
• Webhooks reference
• FTP / SFTP delivery
• Amazon S3 delivery
• API keys