Developer Guide

Getting Started with icana-whisper

Transcribe your first audio file in under 5 minutes. Python and Node.js quickstart with speaker diarization, vocabulary hints, and Australian data residency built in.

What is icana-whisper?

icana-whisper is the transcription API behind Australian Transcription. It's a high-accuracy speech recognition service hosted entirely on AWS infrastructure in Sydney, wrapped in a clean REST API designed to be straightforward to integrate.

Because all processing happens in Australia, your audio never leaves the country — so APP 8 cross-border disclosure obligations under the Privacy Act are never triggered. That matters for any Australian business handling recordings that contain personal information.

  • Speaker diarization — labels each speaker in the transcript automatically
  • Multi-format support — MP3, WAV, OGG, FLAC, M4A
  • Vocabulary hints — prompt the model with domain-specific terms, names, or abbreviations
  • 90 minutes free — no credit card required to get started

Prerequisites

  • Python 3.8+ or Node.js 18+
  • An API key — sign up free, no credit card required
  • An audio file (MP3, WAV, OGG, FLAC, or M4A)

How the API works

The API is asynchronous. You submit a file to POST /api/v1/transcribe and get back a job_id. You then poll GET /api/v1/jobs/{job_id} until the status is completed.

Python quickstart

Install the only dependency you need:

shell 
pip install requests

Then submit a file and poll for the result:

transcribe.py 
import time
import requests

API_KEY = "sk_your_api_key_here"
BASE_URL = "https://api.icana.ai/api/v1"
HEADERS = {"X-API-Key": API_KEY}

# 1. Submit the audio file
with open("audio.mp3", "rb") as f:
    resp = requests.post(
        f"{BASE_URL}/transcribe",
        headers=HEADERS,
        files={"file": f},
        data={"language": "en"},
    )

data = resp.json()
job_id = data["job_id"]
print(f"Job submitted: {job_id}")
print(f"Status: {data['status']}")  # "processing" or "pending"

# 2. Poll until complete
while True:
    result = requests.get(f"{BASE_URL}/jobs/{job_id}", headers=HEADERS).json()
    status = result["status"]
    print(f"Status: {status}")

    if status == "completed":
        print("\nTranscription:")
        print(result["transcription"])
        print("\nSpeaker diarization:")
        print(result["diarization"])
        break
    elif status == "failed":
        print("Job failed.")
        break

    time.sleep(3)

Node.js quickstart

Install the dependencies:

shell 
npm install form-data node-fetch
transcribe.js 
const fs = require("fs");
const FormData = require("form-data");
const fetch = require("node-fetch");

const API_KEY = "sk_your_api_key_here";
const BASE_URL = "https://api.icana.ai/api/v1";

async function transcribe(filePath) {
  const form = new FormData();
  form.append("file", fs.createReadStream(filePath));
  form.append("language", "en");

  const res = await fetch(`${BASE_URL}/transcribe`, {
    method: "POST",
    headers: { "X-API-Key": API_KEY, ...form.getHeaders() },
    body: form,
  });

  const { job_id, status } = await res.json();
  console.log(`Job submitted: ${job_id} (${status})`);

  // Poll for result
  while (true) {
    await new Promise((r) => setTimeout(r, 3000));

    const result = await fetch(`${BASE_URL}/jobs/${job_id}`, {
      headers: { "X-API-Key": API_KEY },
    }).then((r) => r.json());

    if (result.status === "completed") {
      console.log("Transcription:", result.transcription);
      console.log("Diarization:", result.diarization);
      break;
    } else if (result.status === "failed") {
      console.log("Job failed.");
      break;
    }

    console.log("Status:", result.status);
  }
}

transcribe("audio.mp3");

Speaker diarization

The API labels each turn of the conversation automatically. By default it assumes 2 speakers. Pass num_speakers for better accuracy when you know the exact count (1-10):

python 
resp = requests.post(
    f"{BASE_URL}/transcribe",
    headers=HEADERS,
    files={"file": open("meeting.mp3", "rb")},
    data={"language": "en", "num_speakers": 3},
)

The diarization field in a completed job looks like:

output 
[Speaker 1]: Hello, thanks for joining the call.
[Speaker 2]: Happy to be here.
[Speaker 1]: Let's get started.
[Speaker 3]: Quick question before we do...

Improving accuracy with prompts

The prompt parameter lets you hint at domain-specific terms, names, or abbreviations in your audio. Whisper uses this to improve spelling of uncommon words:

python 
data={
    "language": "en",
    "prompt": "ACME Corp, Dr. Nguyen, KPIs, Q3 review, CRM",
}

Keep prompts concise — only the last ~200 tokens (~40-60 words) are used. Focus on terms most likely to be misspelled.

Checking your credit balance

The /api/v1/credit endpoint returns your current AUD balance:

python 
resp = requests.get(f"{BASE_URL}/credit", headers=HEADERS)
print(resp.json())
response 
{
  "balance_aud": "4.80",
  "price_per_minute_aud": "0.02",
  "estimated_remaining_minutes": 240,
  "total_topped_up_aud": "5.00",
  "total_used_aud": "0.20"
}

Rate limits

Endpoints are rate-limited per API key. If you exceed a limit the API returns 429 Too Many Requests with a Retry-After header.

Endpoint Rate limit
POST /api/v1/transcribe 10 requests per minute
All other endpoints 60 requests per minute

API endpoints at a glance

Endpoint Method Description
/api/v1/transcribe POST Submit audio. Returns job_id.
/api/v1/jobs/{'{job_id}'} GET Poll job status. Returns transcription and diarization when complete.
/api/v1/jobs GET List all jobs for your account (paginated).
/api/v1/credit GET Get your AUD credit balance and usage summary.

Full API documentation is available at /docs.

Frequently asked questions

What is icana-whisper?

icana-whisper is the transcription API behind Australian Transcription. It's a high-accuracy audio transcription service hosted entirely on AWS infrastructure in Sydney, Australia. Because all processing happens in Australia, your audio never leaves the country — so APP 8 cross-border disclosure obligations under the Privacy Act are never triggered.

How do I transcribe audio with the API?

The API is asynchronous. Submit your audio file to POST /api/v1/transcribe with your API key and receive a job_id. Then poll GET /api/v1/jobs/{job_id} until the status is completed. The response includes both a plain transcription and speaker-labelled diarization. The whole flow takes under 5 minutes to set up.

What audio formats are supported?

The API accepts MP3, WAV, OGG, FLAC, and M4A files submitted as multipart/form-data.

How do I get speaker labels in my transcript?

Pass the num_speakers parameter when submitting a job. The API will label each segment with the corresponding speaker (Speaker 1, Speaker 2, etc.). You can specify 1 to 10 speakers. Speaker diarization is included in the standard transcription price at no extra cost.

How do I improve accuracy for domain-specific terms?

Use the prompt parameter with comma-separated domain-specific terms, names, or abbreviations (e.g. 'ACME Corp, Dr. Nguyen, APRA, CPS 234'). Keep prompts under 60 words and focus on terms most likely to be misspelled.

Get your free API key

90 minutes free. No credit card required. Australian data residency included.

Start for free API reference

Related reading:

Python Speech-to-Text API Guide APP 8 and Transcription APIs Explained Full API Reference