Menu

Mattering Automations Cartesia integration

Connect Cartesia to Mattering Automations: Sonic text to speech, Ink transcription, voice cloning and localization, speech infill, and credit usage reporting as workflow steps, authenticated with one API key.

The Mattering Automations Cartesia integration adds Cartesia's voice AI to your automation canvas: convert text to speech with the Sonic model family (sonic-3.5 by default), transcribe audio with Ink batch speech to text, clone a voice from a short audio sample, localize a voice into new languages, generate infill speech that splices between existing clips, manage the org's voice library, and read credit and agent usage for guardrail steps.

The credential is a single API key created in the Cartesia Playground. Cartesia requires two headers on every request, the API key and a Cartesia-Version date header, and Mattering sends both automatically, so the only thing you configure is the key. Standard keys cover 11 of the 13 nodes; the two usage reporting nodes need an admin key, which this guide covers. Setup takes a few minutes once the key exists.

The scope is stated plainly. This is a REST integration for voice automation: it generates, transcribes, and manages, and it deliberately excludes Cartesia's streaming transports (the WebSocket and server-sent-events endpoints that power real-time conversation). Of the 13 nodes, 6 read and 7 act, and exactly one carries a destructive flag: Cartesia: Delete Voice, which permanently removes an owned clone or localization. Voice cloning ships with its consent obligation stated on the node: only clone voices you own or have documented consent to clone.

Before you start

  • A Cartesia account. Sign up at the Cartesia Playground (play.cartesia.ai); Cartesia's pricing page lists a Free tier with monthly credits that cover Text to Speech and Speech to Text alongside Pro, Startup, Scale, and Enterprise plans. The page lists a commercial use license from the Pro plan up and does not spell out API access tier by tier, so confirm the tier that fits your use on Cartesia's pricing page.
  • For the two usage reporting nodes, an admin API key (prefixed sk_car_admin_). A standard key (prefixed sk_car_) covers everything else and returns a 403 on those two nodes by design.
  • For voice cloning, transcription, and infill, the audio hosted at a public HTTPS URL. The canvas has no binary file upload, so these nodes download the file from the URL you give them, up to 20 MB per file.
  • A Mattering workspace with access to the Automations app.

Create a Cartesia API key

Mattering authenticates to Cartesia with an API key sent as the X-API-Key header, plus the Cartesia-Version date header that Cartesia requires on every request. The integration pins the current documented version (2026-03-01) and sends both headers for you, so the credential form is just the key. Keys are created and managed in the Cartesia Playground; they are not shown in Cartesia's docs site or dashboard anywhere else.

Sign in to the Cartesia Playground at play.cartesia.ai and open API Keys (play.cartesia.ai/keys).
Create a key. Standard keys are prefixed sk_car_ and cover text to speech, transcription, voices, accents, infill, and the status check.
If your workflows will use Cartesia: Get Credit Usage or Cartesia: Get Agent Usage, create an admin key instead at play.cartesia.ai/keys/admin, prefixed sk_car_admin_. A standard key returns a 403 on those two nodes by design; everything else works with either key.
Copy the key and store it somewhere safe until it is saved in Mattering.
You never configure the Cartesia-Version header. Mattering pins the current documented version and sends it on every request; when Cartesia publishes a new version date, the integration updates it centrally.

Connect Cartesia to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Cartesia from the list.
Click Create new credential, paste the API key, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering calls Cartesia's voices list, which works on every key: a voice list back proves the credential, an error means the key is wrong or revoked. The unauthenticated API status endpoint is deliberately not used as the test, because it succeeds even with a bad key.
Click Connect. All 13 Cartesia nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Cartesia section should list the query and action nodes. Drop Cartesia: List Voices onto the canvas and run a test step. It is the integration's credential health check: it is free, read-only, and returns the voices available to your account, Cartesia library voices plus your org's own clones and localizations, with the IDs that every speech node asks for. If it succeeds, the credential is healthy.

Two expected behaviors worth knowing during verification. Cartesia: Get API Status requires no authentication at all, so it proves connectivity and shows the current API version date but can never prove the key; do not treat its success as a credential check. And Cartesia: Get Credit Usage and Cartesia: Get Agent Usage return a 403 on a standard key, which is Cartesia's design rather than a defect; they need an admin key. Everything in this verify path is read-only and safe to re-run whenever you rotate the key.

Node reference

13 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 6

Cartesia: Get API Status

cartesia_get_api_status

Check that the Cartesia API is up and see the current API version date. This endpoint requires no authentication, so it proves connectivity but not the key; use List Voices to verify the credential.

Cartesia: Get Agent Usage

cartesia_get_agent_usage

Get the org's voice agent usage over a time window as day, week or month buckets: billed cents, agent minutes and call counts per bucket. Requires an ADMIN API key (sk_car_admin_ prefix, created at play.cartesia.ai/keys); a standard key returns 403.

Cartesia: Get Credit Usage

cartesia_get_credit_usage

Get the org's credit consumption over a time window as day, week or month buckets, optionally filtered to one API key or grouped by capability, model, voice or key. Each row carries its bucket's start_ts, end_ts and credits. Requires an ADMIN API key (sk_car_admin_ prefix, created at play.cartesia.ai/keys); a standard key returns 403. The natural guard node before a big TTS batch.

Cartesia: Get Voice

cartesia_get_voice

Get full metadata for one voice: name, tagline, description, gender, language, supported locales and access settings.

Cartesia: List Accents

cartesia_list_accents

List every accent Cartesia supports, with its id, display name, language and locale. Accent ids feed the accent fields on the voice clone, localize and update nodes; an accent must match the voice's language.

Cartesia: List Voices

cartesia_list_voices

List the voices available to this account: Cartesia library voices plus the org's own cloned and localized voices, with their IDs, languages, genders and descriptions. Filter by search text, ownership, gender or language. This is the free lookup that feeds voice_id into every speech node, and the credential health check for the connector.

Action nodes 7

Cartesia: Clone Voice from URL

cartesia_clone_voice_from_url

Clone a new voice from a short audio sample fetched from a public HTTPS URL (flac, mp3, ogg, wav or webm; this node downloads up to 20 MB and uploads it as the clip). Returns the new voice's metadata including its id, ready for the speech nodes; reversible with Delete Voice. Only clone voices you own or have documented consent to clone; you are responsible for having the rights to the sample. Direct file upload is not supported on the canvas, so host the clip at a URL first.

Cartesia: Delete Voice

cartesia_delete_voice

Permanently delete an owned voice (a clone or localization) from this account. The voice cannot be recovered; Cartesia library voices cannot be deleted. Returns an empty 204 on success.

Cartesia: Infill Speech Between Clips

cartesia_infill_from_urls

Generate speech that splices naturally between existing audio clips: give a left and/or right context clip by URL (at least one; this node downloads up to 20 MB each) plus the transcript to infill, and Cartesia matches prosody across the seam. Returns the generated audio as base64 (data.audio_base64) subject to the 5 MB encoded cap. Use the same voice and output format as the surrounding clips.

Cartesia: Localize Voice

cartesia_localize_voice

Create a new voice that speaks a different language with the same vocal character as an existing voice. Returns the new voice's metadata including its id; reversible with Delete Voice.

Cartesia: Text to Speech

cartesia_text_to_speech

Convert text into speech with a Cartesia Sonic voice. Returns the audio as base64 (data.audio_base64) with its content type and byte size; responses over the 5 MB encoded cap fail with a clear error, so use mp3 at a lower bit rate or shorter text for long passages. Billed in credits per character. Timestamped output exists only on Cartesia's WebSocket transport, which is out of scope for this connector.

Cartesia: Transcribe Audio from URL

cartesia_transcribe_audio_from_url

Transcribe an audio file with Cartesia's Ink batch speech-to-text by pointing at a public HTTPS URL (this node downloads up to 20 MB and uploads it for transcription; long files are chunked by Cartesia automatically). Returns the transcript text, detected language, duration and optional per-word timestamps. Billed by audio duration. Direct file upload and realtime streaming are not supported on the canvas, so host the file at a URL first.

Cartesia: Update Voice

cartesia_update_voice

Update an owned voice's metadata: name, tagline, description, gender, accent or access. Omitted fields keep their current values; read them first with Get Voice if you need to restore later. Only voices this org owns (clones and localizations) can be updated.

Using the integration

On the automation canvas

Cartesia nodes chain with every other node: a schedule can pull the week's finished drafts, run Cartesia: Text to Speech on each, and open a review task in Mattering Productivity; an inbound webhook can hand a recording URL to Cartesia: Transcribe Audio from URL and write the transcript into a Mattering database. The voice ID from Cartesia: List Voices is the value almost every downstream node asks for, and the voice pickers on the speech nodes are powered by that same lookup, grouped by language.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter can drive the same surface. An agent can browse voices with Cartesia: List Voices, inspect one with Cartesia: Get Voice, generate audio with Cartesia: Text to Speech, and keep the library tidy with Cartesia: Update Voice. The read nodes are the safest surface to hand an agent; keep Cartesia: Delete Voice, the integration's one destructive node, behind a condition or an approval step.

Getting audio out of a node

Generated audio returns as base64 inside the node output, with its content type and byte size, capped at 5 MB encoded. Cartesia: Text to Speech defaults to the mp3 container for exactly this reason: mp3 at the server default bit rate holds minutes of speech under the cap, where uncompressed wav at 44.1 kHz reaches it in under a minute of audio. A response over the cap fails with a clear error advising mp3 at a lower bit rate or shorter text. For long reads, split the text into sections and generate per section. Timestamped speech output exists only on Cartesia's streaming transports, server-sent events and WebSocket, which are outside this integration; per-word timestamps are available on transcription instead.

The voice lifecycle, with consent stated

Cartesia: Clone Voice from URL creates a new voice from a short audio sample fetched from a public HTTPS URL and returns its ID ready for the speech nodes. The consent obligation is stated on the node itself: only clone voices you own or have documented consent to clone; you are responsible for having the rights to the sample. From there, Cartesia: Localize Voice gives the same vocal character another language, Cartesia: Update Voice maintains name, tagline, gender, accent, and access (omitted fields keep their current values), and Cartesia: Delete Voice retires clones and localizations permanently. Accent values come from Cartesia: List Accents, and an accent must match the voice's language, which is why the accent pickers group by language.

Transcription and infill from URLs

Cartesia: Transcribe Audio from URL runs Ink batch speech to text on a file downloaded from a public HTTPS URL, up to 20 MB, with long files chunked by Cartesia automatically; it returns the transcript, detected language, duration, and optional per-word timestamps, billed by audio duration. Cartesia: Infill Speech Between Clips is the narration repair tool: give a left and a right context clip by URL (at least one) plus the corrected transcript, and Cartesia generates speech that matches prosody across the seam. Use the same voice and output format as the surrounding clips so the splice holds.

Credit guardrails before batch jobs

Cartesia: Get Credit Usage returns credit consumption in day, week, or month buckets, optionally filtered to one API key or grouped by capability, model, or voice, and Cartesia: Get Agent Usage reports voice agent minutes, calls, and billed cents the same way. Both need an admin key. The pattern that pays for itself: before a batch narration run, read the month's consumption, compare against your budget in a condition step, and route to a human approval task instead of the generation step when the remaining credits are thin. Text to speech bills in credits per character, so the guard is worth one extra node.

Troubleshooting

Test Connection fails with an authentication error
The test calls Cartesia's voices list, which accepts every valid key, so a failure here is about the key itself. Check for leading or trailing whitespace from the copy, and confirm the key still exists at play.cartesia.ai under API Keys; a deleted or rotated key fails exactly like a wrong one. One trap to avoid while debugging: the API status node succeeding proves nothing about the key, because that endpoint requires no authentication at all. Verify with the voices list, not the status check.
The usage nodes return 403 while every other node works
Cartesia: Get Credit Usage and Cartesia: Get Agent Usage require an admin API key, prefixed sk_car_admin_, and a standard sk_car_ key gets a 403 there by design rather than by misconfiguration. Create an admin key at play.cartesia.ai/keys/admin and either use it as the connector credential or keep it as a separate credential just for the usage nodes. If your Cartesia role cannot create admin keys, ask the account owner; nothing in Mattering can widen a key's scope.
Text to Speech fails with a response-too-large error
Generated audio is returned as base64 under a 5 MB encoded cap, and the node fails clearly rather than truncating when a response exceeds it. Uncompressed wav at 44.1 kHz reaches the cap in under a minute of audio, which is why mp3 is the default container. Switch to mp3, lower the bit rate, or split long text into sections and generate per section. The same cap applies to Cartesia: Infill Speech Between Clips.
Clone, transcribe, or infill fails with a download error
These nodes fetch their audio from the URL you configure, because the canvas has no binary file upload. The URL must be public HTTPS reachable without cookies or login, the file must be 20 MB or under, and the download must complete within the timeout; a private link, a login wall, an empty response, or an over-cap file fails the node before Cartesia is ever called. Host the clip somewhere directly fetchable and test the URL in a private browser window first. Supported clone formats are flac, mp3, mpeg, mpga, oga, ogg, wav, and webm.
Update Voice or Delete Voice fails on a voice from the library
Only voices your org owns, clones and localizations, can be updated or deleted; Cartesia library voices cannot be, and the node reports the refusal. Check ownership with Cartesia: Get Voice before a lifecycle step. Also remember that delete is permanent: the voice cannot be recovered, so gate the delete node behind a condition or approval step, and read current metadata first with Cartesia: Get Voice if you may need to restore an updated voice's fields later.
A clone or localization rejects the accent value
Accent fields take accent IDs, not display names, and an accent must match the voice's language: a French accent on an English voice is refused. Pick accents through the field's picker, which is powered by Cartesia: List Accents and grouped by language, or run that node directly to see every supported accent with its ID, name, language, and locale.
Infill output sounds wrong at the seam
Cartesia: Infill Speech Between Clips matches prosody against the context clips you give it, so a mismatch is usually an input problem: use the same voice ID and the same output format family as the surrounding clips, and give it clean context audio on at least one side of the gap. If the splice still stands out, widen the context clips so the model hears more of the surrounding delivery, and keep the infilled transcript close in style to the original sentence.
There are no word timestamps on generated speech
That is a scope boundary, not a fault. Cartesia offers timestamped text to speech only on its streaming transports, server-sent events and WebSocket, which this REST integration deliberately excludes. If a workflow needs word timings, generate the audio with Cartesia: Text to Speech and then run Cartesia: Transcribe Audio from URL over the hosted result with per-word timestamps enabled, which returns timings from the transcription side.

Cartesia is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products