Skip to content

Quickstart

Get up and running with the Australian Transcription in under 5 minutes.

Prerequisites

  • An Icana.AI account — register here
  • An API key — see Authentication to create one
  • An audio file (MP3, WAV, OGG, FLAC, M4A, MP4, or WebM)

Step 1: Submit a transcription

Upload your audio file and submit it for transcription in a single request:

curl -X POST https://api.icana.ai/api/v1/transcribe \
  -H "X-API-Key: sk_test_your_api_key_here" \
  -F "file=@meeting-recording.mp3" \
  -F "language=en"

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Job submitted successfully. Poll the status endpoint to check progress."
}

Optional parameters

  • language — Language code (default: en). Supports other languages (see Dashboard for list)
  • prompt — Comma-separated words or abbreviations that appear in the recording, to help the transcriber spell them correctly (e.g. brand names, acronyms, jargon). Keep it under ~50 words.

Step 2: Poll for results

Transcription runs asynchronously. Poll the job status endpoint until the job completes:

curl https://api.icana.ai/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: sk_test_your_api_key_here"

While processing:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "original_filename": "meeting-recording.mp3",
  "language": "en",
  "created_at": "2025-02-03T10:30:00Z"
}

When complete:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "original_filename": "meeting-recording.mp3",
  "language": "en",
  "audio_duration_seconds": 180,
  "audio_duration_minutes": 3.0,
  "transcription": "Thanks everyone for joining today's call. Let's get started with the agenda...",
  "diarization": "[Speaker 1]: Thanks everyone for joining today's call.\n[Speaker 2]: Thanks for having us. Let's get started...",
  "created_at": "2025-02-03T10:30:00Z",
  "completed_at": "2025-02-03T10:32:00Z"
}

Polling strategy

We recommend polling every 5 seconds initially, increasing the interval for longer audio files. Check for terminal statuses completed or failed to stop polling.

Polling script (bash)

JOB_ID="550e8400-e29b-41d4-a716-446655440000"
API_KEY="sk_test_your_api_key_here"

while true; do
  RESPONSE=$(curl -s https://api.icana.ai/api/v1/jobs/$JOB_ID \
    -H "X-API-Key: $API_KEY")

  STATUS=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")

  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    echo "$RESPONSE" | python3 -m json.tool
    break
  fi

  sleep 5
done

Step 3: Check your usage

View how many minutes you've used this billing period:

curl https://api.icana.ai/api/v1/usage \
  -H "X-API-Key: sk_test_your_api_key_here"

{
  "billing_period_start": "2025-02-01",
  "billing_period_end": "2025-02-28",
  "minutes_used": 3.0,
  "minutes_remaining": 57.0,
  "balance_aud": 1.14,
  "price_per_minute_aud": 0.02,
  "plan_name": "Pay As You Go"
}

Supported audio formats

Format Extensions
MP3 .mp3
WAV .wav
OGG .ogg
FLAC .flac
M4A .m4a
MP4 .mp4 (audio track)
WebM .webm

Maximum file size: 100 MB

What's next?