AI — Transcribe

AI — Transcribe

Type: ai-transcribe  ·  Package: AI Activities v1.4.1  ·  Output: string

Since: v1.3.0

Turns an audio file into text: a voice note that came in over WhatsApp, a call recording, the audio of a meeting. It returns the transcript as text, ready to store, search, or pass to AI — Complete or AI — Extract.

Unlike the package’s other activities, it does not use Claude: it works with OpenAI or with any service that exposes the same transcription API (for example, a self-hosted Whisper on your own servers).

How it works

1. Reads the file at path and checks that it exists, has a supported audio extension and is no larger than 25 MB.
2. Sends it to the transcription service with the model, language and prompt you give: with your credential, straight to your service; without it, through the transcription included in your plan via Zoan Cloud.
3. Returns the transcribed text, with no leading or trailing whitespace.

With your credential, the service is taken from it: if it holds a base_url field, the request goes to that address (your own Whisper); otherwise it goes to OpenAI. /v1 is appended to base_url, unless the address already ends in a version segment such as /v1: http://voice.local:8000 and http://voice.local:8000/v1 reach the same place. The key is read from the credential’s value or, for an integration, from its api_key, value, apiKey, key or token fields.

Waits and retries: timeout is the maximum wait for the transcription. With the included transcription, transient failures (congestion, service error, timeout, network) are retried up to 3 times with growing waits. With your own service there are no automatic retries: use a Retry if you need one.

Required parameters

Parameter	Type	Default	Description
path	string	—	Path to the audio file: .ogg, .oga, .opus, .mp3, .m4a, .mp4, .wav, .webm, .flac, .mpeg or .mpga. Up to 25 MB.

Optional parameters

Parameter	Type	Default	Description
credential	credential	—	Your own OpenAI integration (api_key and, if you use your own Whisper, base_url). Leave it empty to use the transcription included in your Zoan Cloud plan: nothing to set up, and the usage shows up in AI Usage. Optional since 1.4.0.
model	string	"gpt-4o-mini-transcribe"	Transcription model id. With the included transcription, empty uses the plan’s default model. With your own Whisper, use whisper-1.
language	string	—	Audio language as an ISO 639-1 code ("es", "en", "pt"). Improves accuracy; empty auto-detects.
prompt	string	—	A hint with names, acronyms or vocabulary that may appear in the audio.
timeout	int	600	Seconds to wait, between 1 and 3600.
usageVariable	string	—	Name of a variable (declare it as an object) to store the usage in: { model, bytes, seconds }.

No credential: the transcription included in your plan

credential is optional since 1.4.0:

• Empty: if your Zoan Cloud plan includes AI, the activity uses Zoan’s account through Zoan Cloud. You don’t create keys or sign up with a provider: the robot works from its first run, and what it uses shows up in AI Usage and counts toward the usage included in your plan. It works in Zoan Cloud runs and in Designer tests with your session open.
• With your credential: the call goes straight from the robot to your provider, with your key and your terms. Zoan Cloud only records the usage (model and seconds) so you can see it in the same panel; the content never goes through Zoan Cloud and that usage does not count against what is included. A self-hosted service that is not the OpenAI API is recorded separately, so it is not costed as OpenAI.

With the included transcription you can use the OpenAI transcription models in the Zoan Cloud catalog, and what counts is the duration reported by the transcription service when it gives one (the Whisper models). With the gpt-4o-*-transcribe models, which do not report it, the duration is measured from the file itself when the format allows it and otherwise estimated from its size. The audio travels through Zoan Cloud to the provider without being stored —only the usage is recorded.

Audio does not go through personal data masking: if that matters, transcribe first and process the text with AI — Complete or AI — Extract, which do mask.

Output

Returns a string with the transcribed text, with no leading or trailing whitespace. If the service answers with no text, it returns an empty string.

If you set usageVariable, that variable also receives an object with the model used (model), the file size in bytes (bytes) and the audio duration in seconds (seconds, one decimal). The duration is read from the file itself when the format allows it (Ogg/Opus, WAV, MP4/M4A); otherwise it is an estimate based on the size.

The prompt helps with unusual words

The model transcribes everyday speech well, but it can get proper names, brands, acronyms or industry terms wrong. The prompt is not an instruction; it is a list of words that are likely to appear:

prompt → "Andean Distributors, Ms. Valencia, purchase order, VAT, credit note"

With that, acronyms and industry terms come out spelled right, and the company name and the customer’s surname are written as they should be.

Example

Transcribe a voice note with the included transcription and summarise it:

AI — Transcribe   path     = voiceNotePath
                  language = "en"
                  → output: transcript
AI — Complete     system = "Summarise the message in one line."
                  prompt = transcript
                  → output: summary

Transcribe the recordings in a folder with your own integration and log how many seconds were processed:

For Each   items = recordings   itemVariable = audio
 └─ activities:
      AI — Transcribe   credential    = credential("openai")
                        path          = audio
                        usageVariable = usage
                        → output: text
      Log   message = "Transcribed " + usage["seconds"] + " s of " + audio

Set the language if you know it

Leaving language empty works, but on short or noisy audio the model may get the language wrong. If all your audio is in English, set "en".

Audio larger than 25 MB

A normal voice note or call stays well below it; for long recordings, split them into chunks or compress them (for example, to .mp3 or .ogg) before transcribing.

Common errors

Message	Cause and fix
'path' is required.	No file was given.
Audio file not found.	The path does not exist on the machine running the robot.
Unsupported audio extension '…'. Use .ogg, .opus, .mp3, .m4a, .wav, .webm or .flac.	The file is not in a supported format. Convert it to .mp3, .ogg or .wav.
The audio exceeds 25 MB. Split it or compress it first.	The file is too large. Split or compress it.
'timeout' must be between 1 and 3600 seconds. Received: …	timeout out of range or not an integer.
The credential does not contain an API key. Use an OpenAI integration from Center › Resources › Integrations in Zoan Cloud.	The credential exists but does not hold the API key.
Transcription service answered HTTP 401: …	With your credential: the API key is invalid or revoked. Other codes carry the service’s detail.
Choose a credential or turn on the AI included in your plan. The included AI goes through Zoan Cloud: …	No credential and no Zoan Cloud in the run (for example, a test without a session). Sign in or use your integration.
Choose a credential or turn on the AI included in your plan.	No credential and your plan does not include AI.
The AI usage included in your plan for this month has been reached. Use your own credential or upgrade the plan.	All the AI usage included this month is spent. With your own credential the robot keeps going.
The model '…' is not available in the AI included in your plan. …	Leave model empty or pick a model from the Zoan Cloud catalog.
The request is too large for the AI included in your plan (… 25 MB of audio …).	The audio is over the plan’s limit. Split or compress it.
The AI provider did not answer in time through Zoan Cloud. Try again, or raise 'timeout'.	The service took longer than timeout on every attempt. Raise timeout for long audio.

Related activities

• AI — Complete — summarise, classify or answer questions about the transcript.
• AI — Extract — pull specific fields out of what was said.