Fjalim API

curl

export FJALIM_KEY="fj_live_..."          # create a key in the web app
API=https://api.fjalim.com
FILE=seanca.mp3
SIZE=$(wc -c < "$FILE" | tr -d ' ')

# 1. Ask for an upload URL
UPLOAD=$(curl -sS "$API/v1/uploads" \
  -H "Authorization: Bearer $FJALIM_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\":\"$FILE\",\"content_type\":\"audio/mpeg\",\"size_bytes\":$SIZE}")
UPLOAD_ID=$(echo "$UPLOAD" | jq -r .id)
UPLOAD_URL=$(echo "$UPLOAD" | jq -r .upload_url)

# 2. PUT the bytes, with the headers from the response
HEADERS=()
while IFS= read -r h; do HEADERS+=(-H "$h"); done \
  < <(echo "$UPLOAD" | jq -r '.headers | to_entries[] | "\(.key): \(.value)"')
curl -sS -X PUT "$UPLOAD_URL" "${HEADERS[@]}" --data-binary @"$FILE"

# 3. Confirm the upload
curl -sS -X POST "$API/v1/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $FJALIM_KEY"

# 4. Create the transcription
JOB=$(curl -sS "$API/v1/transcriptions" \
  -H "Authorization: Bearer $FJALIM_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"upload_id\":\"$UPLOAD_ID\"}" | jq -r .id)

# 5. Poll until it finishes (or use a webhook)
while :; do
  STATUS=$(curl -sS "$API/v1/transcriptions/$JOB" \
    -H "Authorization: Bearer $FJALIM_KEY" | jq -r .status)
  echo "$STATUS"
  [ "$STATUS" = completed ] && break
  [ "$STATUS" = failed ] || [ "$STATUS" = canceled ] && exit 1
  sleep 3
done

# 6. Export
curl -sS "$API/v1/transcriptions/$JOB/transcript?format=srt" \
  -H "Authorization: Bearer $FJALIM_KEY" -o seanca.srt

JavaScript

// Node 20+ (global fetch). Run as an ES module.
import { readFile, writeFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

const API = 'https://api.fjalim.com';
const KEY = process.env.FJALIM_KEY; // fj_live_...

async function call(path, init = {}) {
  const res = await fetch(API + path, {
    ...init,
    headers: { Authorization: `Bearer ${KEY}`, ...init.headers },
  });
  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message}`);
  }
  return res;
}
const json = { 'Content-Type': 'application/json' };

const file = await readFile('seanca.mp3');

// 1. Ask for an upload URL
const upload = await (await call('/v1/uploads', {
  method: 'POST',
  headers: json,
  body: JSON.stringify({ filename: 'seanca.mp3', content_type: 'audio/mpeg', size_bytes: file.length }),
})).json();

// 2. PUT the bytes, with the headers from the response
const put = await fetch(upload.upload_url, { method: upload.method, headers: upload.headers, body: file });
if (!put.ok) throw new Error(`upload failed: ${put.status}`);

// 3. Confirm the upload
await call(`/v1/uploads/${upload.id}/complete`, { method: 'POST' });

// 4. Create the transcription
const job = await (await call('/v1/transcriptions', {
  method: 'POST',
  headers: { ...json, 'Idempotency-Key': randomUUID() },
  body: JSON.stringify({ upload_id: upload.id }),
})).json();

// 5. Poll until it finishes (or use a webhook)
let t;
do {
  await new Promise((r) => setTimeout(r, 3000));
  t = await (await call(`/v1/transcriptions/${job.id}`)).json();
} while (!['completed', 'failed', 'canceled'].includes(t.status));
if (t.status !== 'completed') throw new Error(t.error?.message ?? t.status);

// 6. Export
const srt = await (await call(`/v1/transcriptions/${job.id}/transcript?format=srt`)).text();
await writeFile('seanca.srt', srt);

Python

# pip install httpx
import os
import time
import uuid

import httpx

API = "https://api.fjalim.com"
client = httpx.Client(
    base_url=API,
    headers={"Authorization": f"Bearer {os.environ['FJALIM_KEY']}"},  # fj_live_...
    timeout=30,
)


def check(res: httpx.Response) -> httpx.Response:
    if res.is_error:
        err = res.json()["error"]
        raise RuntimeError(f"{err['code']}: {err['message']}")
    return res


with open("seanca.mp3", "rb") as f:
    data = f.read()

# 1. Ask for an upload URL
upload = check(client.post("/v1/uploads", json={
    "filename": "seanca.mp3",
    "content_type": "audio/mpeg",
    "size_bytes": len(data),
})).json()

# 2. PUT the bytes, with the headers from the response
check(httpx.put(upload["upload_url"], headers=upload["headers"], content=data, timeout=600))

# 3. Confirm the upload
check(client.post(f"/v1/uploads/{upload['id']}/complete"))

# 4. Create the transcription
job = check(client.post(
    "/v1/transcriptions",
    json={"upload_id": upload["id"]},
    headers={"Idempotency-Key": str(uuid.uuid4())},
)).json()

# 5. Poll until it finishes (or use a webhook)
while True:
    time.sleep(3)
    t = check(client.get(f"/v1/transcriptions/{job['id']}")).json()
    if t["status"] in ("completed", "failed", "canceled"):
        break
if t["status"] != "completed":
    raise RuntimeError((t.get("error") or {}).get("message", t["status"]))

# 6. Export
srt = check(client.get(f"/v1/transcriptions/{job['id']}/transcript", params={"format": "srt"})).text
open("seanca.srt", "w", encoding="utf-8").write(srt)

curl

curl https://api.fjalim.com/v1/transcriptions \
  -H "Authorization: Bearer $FJALIM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/podcast/episodi-42.mp3"}'

JavaScript

const res = await fetch('https://api.fjalim.com/v1/transcriptions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.FJALIM_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ audio_url: 'https://example.com/podcast/episodi-42.mp3' }),
});
const job = await res.json(); // 202 { id, status: "queued", ... }

Python

job = httpx.post(
    "https://api.fjalim.com/v1/transcriptions",
    headers={"Authorization": f"Bearer {os.environ['FJALIM_KEY']}"},
    json={"audio_url": "https://example.com/podcast/episodi-42.mp3"},
).json()  # 202 {"id": ..., "status": "queued", ...}

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

/**
 * rawBody: the exact bytes received (Buffer or string), before any JSON parsing.
 * secret:  your webhook secret, the full string including the "whsec_" prefix.
 */
export function verifyFjalimSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    String(header ?? '').split(',').map((p) => p.trim().split('=', 2)),
  );
  const t = parts.t;
  const v1 = parts.v1;
  if (!/^\d+$/.test(t ?? '') || !/^[0-9a-f]+$/i.test(v1 ?? '')) return false;

  // Reject old (or future) timestamps: replay protection.
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;

  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody, 'utf8');
  const expected = createHmac('sha256', secret)
    .update(Buffer.concat([Buffer.from(`${t}.`), body]))
    .digest();
  const given = Buffer.from(v1, 'hex');
  return given.length === expected.length && timingSafeEqual(given, expected);
}

// Express: read the body as raw bytes so the signature matches.
import express from 'express';
const app = express();
app.post('/hooks/fjalim', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyFjalimSignature(req.body, req.get('Fjalim-Signature'), process.env.FJALIM_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  // Handle event.event === 'transcription.completed' | 'transcription.failed'.
  // Deliveries can repeat: de-duplicate on event.id.
  res.sendStatus(200);
});

Python

import hashlib
import hmac
import os
import time


def verify_fjalim_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    """raw_body: the exact bytes received. secret: the full whsec_... string."""
    try:
        parts = dict(p.strip().split("=", 1) for p in (header or "").split(","))
        t, v1 = parts["t"], parts["v1"]
        timestamp = int(t)
    except (KeyError, ValueError):
        return False

    # Reject old (or future) timestamps: replay protection.
    if abs(time.time() - timestamp) > tolerance:
        return False

    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)


# FastAPI
from fastapi import FastAPI, HTTPException, Request

app = FastAPI()


@app.post("/hooks/fjalim")
async def fjalim_hook(request: Request):
    raw = await request.body()  # bytes, before JSON parsing
    secret = os.environ["FJALIM_WEBHOOK_SECRET"]  # the full whsec_... string
    if not verify_fjalim_signature(raw, request.headers.get("Fjalim-Signature", ""), secret):
        raise HTTPException(status_code=400)
    event = await request.json()
    # De-duplicate on event["id"]; handle transcription.completed / .failed
    return {"ok": True}