Skip to content

API Endpoints

Base URL: https://api.icana.ai/api/v1

All endpoints require an X-API-Key header. See Authentication.

POST /transcribe

Submit an audio file for transcription and speaker diarization.

Request

Content-Type: multipart/form-data

Parameter Type Required Description
file file Yes Audio file (MP3, WAV, OGG, FLAC, M4A, MP4, WebM). Max 100 MB.
language string No Language code (default: en). Supports other languages.
prompt string No Comma-separated words or abbreviations that appear in the recording, to help the transcriber spell them correctly (e.g. brand names, acronyms, jargon). Only the last ~200 tokens are used, so keep it under ~50 words.

Response 200 OK

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

Errors

Status Description
400 Unsupported file type or missing file
401 Invalid or missing API key
402 Insufficient credit balance (minimum $0.50 AUD required)
500 Internal server error

Example

curl -X POST https://api.icana.ai/api/v1/transcribe \
  -H "X-API-Key: sk_test_your_api_key_here" \
  -F "file=@recording.mp3" \
  -F "language=en" \
  -F "prompt=Icana, APAC, CallCoach, AUD"

GET /jobs/{job_id}

Get the status and results of a transcription job.

Path parameters

Parameter Type Description
job_id UUID The job ID returned from /transcribe

Response 200 OK

The response fields vary depending on the job status.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "original_filename": "recording.mp3",
  "language": "en",
  "audio_duration_seconds": null,
  "audio_duration_minutes": null,
  "transcription": null,
  "diarization": null,
  "error_message": null,
  "created_at": "2025-02-03T10:30:00Z",
  "completed_at": null
}

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

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "original_filename": "recording.mp3",
  "language": "en",
  "audio_duration_seconds": null,
  "audio_duration_minutes": null,
  "transcription": null,
  "diarization": null,
  "error_message": "Transcription failed",
  "created_at": "2025-02-03T10:30:00Z",
  "completed_at": "2025-02-03T10:30:45Z"
}

Job statuses

Status Description
pending Job is queued and waiting to be processed
uploading Audio file is being uploaded
processing Transcription is in progress
completed Transcription finished successfully — results available
failed Transcription failed — check error_message for details

Errors

Status Description
401 Invalid or missing API key
404 Job not found (or belongs to a different user)

Example

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

GET /jobs

List all transcription jobs for your account, with optional filtering and pagination.

Query parameters

Parameter Type Default Description
page integer 1 Page number (minimum: 1)
page_size integer 20 Items per page (minimum: 1, maximum: 100)
status string — Filter by job status: pending, uploading, processing, completed, failed

Response 200 OK

{
  "jobs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "original_filename": "recording.mp3",
      "language": "en",
      "audio_duration_seconds": 180,
      "audio_duration_minutes": 3.0,
      "error_message": null,
      "created_at": "2025-02-03T10:30:00Z",
      "completed_at": "2025-02-03T10:32:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20,
  "total_pages": 3
}

Note

The job list response does not include transcription or diarization text. Use GET /jobs/{job_id} to retrieve full results for a specific job.

Errors

Status Description
401 Invalid or missing API key

Example

# List all completed jobs, page 2
curl "https://api.icana.ai/api/v1/jobs?status=completed&page=2&page_size=10" \
  -H "X-API-Key: sk_test_your_api_key_here"

GET /usage

Get a usage summary for the current billing period.

Response 200 OK

{
  "billing_period_start": "2025-02-01",
  "billing_period_end": "2025-02-28",
  "included_minutes": 0,
  "minutes_used": 45.5,
  "minutes_remaining": 0,
  "plan_name": "Pay As You Go",
  "balance_aud": 8.29,
  "price_per_minute_aud": 0.02
}
Field Description
billing_period_start First day of the current billing period
billing_period_end Last day of the current billing period
minutes_used Total minutes transcribed this period
balance_aud Current credit balance in AUD
price_per_minute_aud Price per minute of audio ($0.02 AUD)
plan_name Always Pay As You Go for the credit-based system

Errors

Status Description
401 Invalid or missing API key

Example

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