SDK Code Samples

Use the official Node SDK for production. Raw HTTP samples below for non-Node integrators.

RecommendedNode >== 18

@capsiynau/sdk-transcribe

Official Node SDK. Wraps POST /api/v1/transcribe, job polling, and transcript retrieval. Welsh and English first-class. Typed errors (AuthError, PlanGateError, QuotaError, and more) parsed automatically.

npm install @capsiynau/sdk-transcribe

import { TranscriptionClient } from '@capsiynau/sdk-transcribe'
const client = new TranscriptionClient({ apiKey: process.env.CAPSIYNAU_API_KEY })

const projectId = '00000000-0000-0000-0000-000000000000' // your project UUID
const fileUrl   = 'https://example.com/audio.mp4'        // direct media URL

const job = await client.submit({ projectId, fileUrl, language: 'cy' })
await client.waitFor(job.jobId)
const transcript = await client.getTranscript(job.projectId)
console.log(transcript.segments[0].text)
npm|Source code|REST API reference
Raw HTTP samples below show direct REST calls for Python and curl. Not needed if you're using the Node SDK above.

Transcription flow

Submit a project, poll until done, fetch the JSON transcript.

import requests
import time

API_KEY = "ck_live_YOUR_KEY"
BASE_URL = "https://www.capsiynau.com"  # apex 301-redirects strip Authorization

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def transcribe(project_id: str, file_url: str, language: str = "cy"):
    # 1. Submit
    r = requests.post(
        f"{BASE_URL}/api/v1/transcribe",
        headers=HEADERS,
        json={"projectId": project_id, "fileUrl": file_url, "sourceLanguage": language},
    )
    r.raise_for_status()
    job_id = r.json()["jobId"]
    print(f"Job submitted: {job_id}")

    # 2. Poll until done (or cancelled / failed)
    while True:
        sr = requests.get(
            f"{BASE_URL}/api/v1/status",
            headers={"Authorization": HEADERS["Authorization"]},
            params={"jobId": job_id},
        )
        sr.raise_for_status()  # surface 401/404/5xx instead of looping forever
        s = sr.json().get("job", {})
        status = s.get("status")
        print(f"Status: {status}")
        if status in ("done", "completed"):
            break
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"Job {status}: {s.get('error')}")
        time.sleep(2)

    # 3. Export the transcript as JSON
    e = requests.get(
        f"{BASE_URL}/api/v1/export",
        headers={"Authorization": HEADERS["Authorization"]},
        params={"projectId": project_id, "format": "json", "track": "original"},
    )
    e.raise_for_status()
    return e.json()


if __name__ == "__main__":
    transcript = transcribe(
        project_id="00000000-0000-0000-0000-000000000000",
        file_url="https://example.com/audio.mp4",
        language="cy",
    )
    print(f"Segments: {len(transcript['segments'])}")
    print(transcript["segments"][0]["text"])