Python Examples¶
Complete working examples using the requests library.
Setup¶
import requests
import time
BASE_URL = "https://api.icana.ai/api/v1"
API_KEY = "sk_test_your_api_key_here" # Use an environment variable in production!
HEADERS = {"X-API-Key": API_KEY}
Submit a transcription¶
def transcribe(file_path, language="en", prompt=None):
"""Upload an audio file and submit it for transcription."""
with open(file_path, "rb") as f:
files = {"file": (file_path.split("/")[-1], f)}
data = {"language": language}
if prompt:
data["prompt"] = prompt
response = requests.post(
f"{BASE_URL}/transcribe",
headers=HEADERS,
files=files,
data=data,
)
response.raise_for_status()
return response.json()
result = transcribe("meeting.mp3", language="en", prompt="Icana, APAC, CallCoach, AUD")
print(f"Job ID: {result['job_id']}")
# Job ID: 550e8400-e29b-41d4-a716-446655440000
Poll for results¶
def poll_job(job_id, interval=5, max_attempts=120):
"""Poll a job until it completes or fails."""
for attempt in range(max_attempts):
response = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers=HEADERS,
)
response.raise_for_status()
job = response.json()
status = job["status"]
print(f"Attempt {attempt + 1}: {status}")
if status == "completed":
return job
elif status == "failed":
raise Exception(f"Job failed: {job.get('error_message')}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} did not complete after {max_attempts} attempts")
job = poll_job(result["job_id"])
print(f"Transcription: {job['transcription'][:200]}...")
print(f"Duration: {job['audio_duration_minutes']:.1f} minutes")
List jobs¶
def list_jobs(page=1, page_size=20, status=None):
"""List transcription jobs with optional filtering."""
params = {"page": page, "page_size": page_size}
if status:
params["status"] = status
response = requests.get(
f"{BASE_URL}/jobs",
headers=HEADERS,
params=params,
)
response.raise_for_status()
return response.json()
result = list_jobs(status="completed", page_size=5)
print(f"Total jobs: {result['total']}")
for job in result["jobs"]:
print(f" {job['id']} - {job['original_filename']} ({job['audio_duration_minutes']:.1f} min)")
Check usage¶
def get_usage():
"""Get usage summary for the current billing period."""
response = requests.get(
f"{BASE_URL}/usage",
headers=HEADERS,
)
response.raise_for_status()
return response.json()
usage = get_usage()
print(f"Minutes used: {usage['minutes_used']}")
print(f"Balance: ${usage['balance_aud']} AUD")
Complete example¶
End-to-end script that transcribes a file and prints the results:
import os
import requests
import time
BASE_URL = "https://api.icana.ai/api/v1"
API_KEY = os.environ["ICANA_API_KEY"]
HEADERS = {"X-API-Key": API_KEY}
def transcribe_file(file_path, language="en", prompt=None):
"""Transcribe an audio file and return the results."""
# 1. Submit the file
print(f"Submitting {file_path}...")
with open(file_path, "rb") as f:
files = {"file": (os.path.basename(file_path), f)}
data = {"language": language}
if prompt:
data["prompt"] = prompt
response = requests.post(
f"{BASE_URL}/transcribe",
headers=HEADERS,
files=files,
data=data,
)
response.raise_for_status()
job_id = response.json()["job_id"]
print(f"Job submitted: {job_id}")
# 2. Poll for results
while True:
response = requests.get(f"{BASE_URL}/jobs/{job_id}", headers=HEADERS)
response.raise_for_status()
job = response.json()
if job["status"] == "completed":
print(f"Completed in {job['audio_duration_minutes']:.1f} minutes of audio")
return job
elif job["status"] == "failed":
raise Exception(f"Transcription failed: {job.get('error_message')}")
print(f" Status: {job['status']}...")
time.sleep(5)
if __name__ == "__main__":
result = transcribe_file("meeting.mp3")
print("\n--- Transcription ---")
print(result["transcription"])
print("\n--- Speaker Diarization ---")
print(result["diarization"])
Run it: