harmar-ai 0.1.0

package/dist/mcp.js

@@ -0,0 +1,207 @@
+// `harmar mcp` — Model Context Protocol server over stdio.
+//
+// Gives any MCP host (Claude Code, Claude Desktop, Cursor, Windsurf, …)
+// the Harmar subtitle API as tools. One process per host, authenticated
+// by HARMAR_API_KEY in its environment:
+//
+//   claude mcp add harmar -e HARMAR_API_KEY=hk_live_… -- npx -y harmar-ai mcp
+//
+// Every tool is a thin wrapper over HarmarClient — the MCP layer adds
+// schemas and text rendering, never logic.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { HarmarClient, HarmarError } from "./client.js";
+const server = new McpServer({ name: "harmar", version: "0.1.0" });
+let clientInstance = null;
+function client() {
+    if (!clientInstance)
+        clientInstance = new HarmarClient();
+    return clientInstance;
+}
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+const json = (v) => text(JSON.stringify(v, null, 2));
+// Errors go back as tool results, not protocol errors, so the model can
+// read the code (insufficient_credits carries seconds_needed) and act.
+async function guarded(fn) {
+    try {
+        return await fn();
+    }
+    catch (e) {
+        if (e instanceof HarmarError) {
+            return {
+                isError: true,
+                ...json({ error: { code: e.code, message: e.message, status: e.status, ...e.params } }),
+            };
+        }
+        return { isError: true, ...text(`Error: ${e?.message ?? String(e)}`) };
+    }
+}
+// A completed transcript can be tens of thousands of words. The status
+// tool returns the compact form by default; words come on request.
+function compact(t, includeWords) {
+    if (t.status !== "completed")
+        return t;
+    const { words, translation, ...rest } = t;
+    const out = {
+        ...rest,
+        word_count: words?.length,
+        ...(includeWords ? { words } : {}),
+    };
+    if (translation) {
+        out.translation = includeWords
+            ? translation
+            : { text: translation.text, segments: translation.segments, word_count: translation.words?.length };
+    }
+    return out;
+}
+const OPTIONS_SHAPE = {
+    timestamps: z.enum(["word", "segment", "none"]).optional().describe("Timing granularity in the result (default word)."),
+    punctuation: z.boolean().optional().describe("Keep punctuation (default true)."),
+    speakers: z.boolean().optional().describe("Keep dialogue dashes and speaker ids (default true)."),
+    lyrics: z.enum(["exclude", "include"]).optional().describe("Whether sung lines appear (default exclude)."),
+};
+server.registerTool("harmar_transcribe", {
+    title: "Transcribe a media file",
+    description: "Upload a local audio/video file (MP4, MOV, WebM, M4A, MP3, WAV; ≤60 min) to Harmar and get a word-timed transcript. " +
+        "Best for Armenian and mixed Armenian/Russian/English speech; 50+ other languages supported (see harmar_languages). " +
+        "Charged per second of media from a prepaid balance, refunded if the job fails. " +
+        "Waits for completion by default; if it times out the job keeps running — poll with harmar_get_transcript.",
+    inputSchema: {
+        file_path: z.string().describe("Absolute path to the media file on this machine."),
+        source_lang: z
+            .string()
+            .optional()
+            .describe('Language of the speech, e.g. "hy", "ru", "en", "kk". "auto" identifies it from the audio. Default "hy".'),
+        translate_to: z.string().optional().describe("Also produce a translated subtitle track in this language (no surcharge)."),
+        script_text: z.string().optional().describe("If you already have the exact spoken text, align it instead of transcribing."),
+        webhook_url: z.string().optional().describe("HTTPS URL to notify on completion (Harmar-Signature HMAC header)."),
+        options: z.object(OPTIONS_SHAPE).optional(),
+        keep_media: z
+            .boolean()
+            .optional()
+            .describe("Keep the source video after transcription so harmar_export can burn styled captions into it. Set true whenever a video export is wanted. Default false (media deleted right after the transcript)."),
+        wait: z.boolean().optional().describe("Wait for the result (default true)."),
+        timeout_seconds: z.number().optional().describe("Max seconds to wait (default 900). The job continues server-side after."),
+        include_words: z.boolean().optional().describe("Include the per-word array in the result (default false — text and segments only)."),
+    },
+}, async (a) => guarded(async () => {
+    const result = await client().transcribe(a.file_path, {
+        sourceLang: a.source_lang,
+        translateTo: a.translate_to,
+        scriptText: a.script_text,
+        webhookUrl: a.webhook_url,
+        keepMedia: a.keep_media,
+        options: a.options,
+        wait: a.wait ?? true,
+        timeoutMs: (a.timeout_seconds ?? 900) * 1000,
+    });
+    return json(compact(result, a.include_words ?? false));
+}));
+server.registerTool("harmar_get_transcript", {
+    title: "Get a transcript / job status",
+    description: "Status of a Harmar job by id. While processing: progress 0–100 and, for auto jobs, the detected language. " +
+        "When completed: text, sentence segments, and optionally every word with start/end seconds.",
+    inputSchema: {
+        id: z.string().describe("Transcript id returned by harmar_transcribe."),
+        include_words: z.boolean().optional().describe("Include the per-word array (default false)."),
+    },
+}, async (a) => guarded(async () => json(compact(await client().get(a.id), a.include_words ?? false))));
+server.registerTool("harmar_get_subtitles", {
+    title: "Get SRT or VTT",
+    description: "Subtitle file text for a completed job, one cue per sentence. `lang` picks the track: omit for the source language, " +
+        "or name the translate_to language for the translated track.",
+    inputSchema: {
+        id: z.string(),
+        format: z.enum(["srt", "vtt"]),
+        lang: z.string().optional().describe("Track language; omit for the source track."),
+    },
+}, async (a) => guarded(async () => text(await client().subtitles(a.id, a.format, a.lang))));
+server.registerTool("harmar_languages", {
+    title: "List supported languages",
+    description: "Languages accepted for source_lang and translate_to, live from the API. `auto_detectable: false` means the language works but must be named explicitly.",
+    inputSchema: {},
+}, async () => guarded(async () => json({ auto: "identify from the audio", languages: await client().languages() })));
+server.registerTool("harmar_balance", { title: "Prepaid balance", description: "Seconds and minutes of media the account can still transcribe.", inputSchema: {} }, async () => guarded(async () => json(await client().balance())));
+server.registerTool("harmar_usage", { title: "Usage ledger", description: "The last 100 credit ledger entries (grants, charges, refunds).", inputSchema: {} }, async () => guarded(async () => json(await client().usage())));
+server.registerTool("harmar_pricing", { title: "Pricing", description: "Live per-minute rates and credit packs, so a margin can be computed without hard-coding a number.", inputSchema: {} }, async () => guarded(async () => json(await client().pricing())));
+server.registerTool("harmar_delete_transcript", {
+    title: "Delete a transcript",
+    description: "Purge a finished job's transcript and media now instead of waiting for retention. Idempotent; 409 while still processing.",
+    inputSchema: { id: z.string() },
+}, async (a) => guarded(async () => json(await client().delete(a.id))));
+// ── styles & export ────────────────────────────────────────────────────
+const STYLE_SHAPE = z
+    .object({
+    preset: z.enum(["karaoke", "pill", "popin", "classic", "reveal", "stack", "carousel"]).optional(),
+    font: z.string().optional().describe("A font key from harmar_list_styles — check it renders the track's language."),
+    fontByLang: z.record(z.string(), z.string()).optional(),
+    fontSizePct: z.number().optional().describe("Font size as % of video width (0.5–30)."),
+    color: z.string().optional(),
+    accentColor: z.string().optional(),
+    bgColor: z.string().optional(),
+    bgOpacity: z.number().optional(),
+    position: z.enum(["top", "center", "bottom"]).optional(),
+    posX: z.number().optional(),
+    posY: z.number().optional(),
+    subtitleWidth: z.number().optional(),
+})
+    .passthrough()
+    .describe("A style object. Any field from harmar_list_styles is accepted; unknown fields are rejected by the API with the field list.");
+server.registerTool("harmar_list_styles", {
+    title: "Style catalog",
+    description: "Everything a subtitle style can be: the caption presets (pill, karaoke, popin, …), every font with the languages it actually renders, " +
+        "each style field with its range, and the default style per video orientation. Read this before composing a style.",
+    inputSchema: {},
+}, async () => guarded(async () => json(await client().styles())));
+server.registerTool("harmar_list_style_presets", { title: "Saved styles", description: "The account's saved style presets — pass a preset's id to harmar_export as style_preset_id.", inputSchema: {} }, async () => guarded(async () => json(await client().stylePresets())));
+server.registerTool("harmar_save_style", {
+    title: "Save a style preset",
+    description: "Save a style under a name so every later export uses exactly it (harmar_export with style_preset_id). Up to 10 per account. " +
+        "Compose the style from harmar_list_styles; the API validates it and names any field it rejects.",
+    inputSchema: { name: z.string().min(1).max(60), style: STYLE_SHAPE },
+}, async (a) => guarded(async () => json(await client().saveStylePreset(a.name, a.style))));
+server.registerTool("harmar_delete_style_preset", { title: "Delete a style preset", description: "Remove a saved style by id.", inputSchema: { id: z.string() } }, async (a) => guarded(async () => json(await client().deleteStylePreset(a.id))));
+server.registerTool("harmar_export", {
+    title: "Export a captioned video",
+    description: "Burn styled subtitles into the video of a completed transcript and get an MP4 (no watermark, up to 1080p). " +
+        "Pass exactly one of style_preset_id (a saved style — the reliable way to reuse a specific look) or style (inline). " +
+        "The transcript must have been created with keep_media: true; otherwise the API answers media_purged and the file must be transcribed again with keep_media. " +
+        "Charged per second of media at the transcription rate, refunded if the render fails. Waits by default; pass save_to to download the MP4 to a local path.",
+    inputSchema: {
+        id: z.string().describe("Transcript id."),
+        style_preset_id: z.string().optional(),
+        style: STYLE_SHAPE.optional(),
+        lang: z.string().optional().describe("Track to burn: the source language (default) or the translate_to language."),
+        platform: z.enum(["instagram", "youtube", "tiktok"]).optional(),
+        save_to: z.string().optional().describe("Absolute local path for the MP4. Without it the result carries a signed download_url valid for an hour."),
+        wait: z.boolean().optional().describe("Wait for the render (default true)."),
+        timeout_seconds: z.number().optional().describe("Max seconds to wait (default 1800). The render continues server-side after."),
+    },
+}, async (a) => guarded(async () => {
+    const state = await client().exportVideo(a.id, {
+        stylePresetId: a.style_preset_id,
+        style: a.style,
+        lang: a.lang,
+        platform: a.platform,
+        wait: a.wait ?? true,
+        timeoutMs: (a.timeout_seconds ?? 1800) * 1000,
+        outPath: a.save_to,
+    });
+    return json(a.save_to && state.status === "completed" ? { ...state, file: a.save_to } : state);
+}));
+server.registerTool("harmar_get_export", {
+    title: "Export status",
+    description: "State of a transcript's export: queued / rendering (with progress) / completed (with a signed download_url) / failed (with the reason and the refund).",
+    inputSchema: { id: z.string(), save_to: z.string().optional().describe("If completed, download the MP4 to this local path.") },
+}, async (a) => guarded(async () => {
+    const state = await client().getExport(a.id);
+    if (a.save_to && state.status === "completed") {
+        await client().downloadExport(state, a.save_to);
+        return json({ ...state, file: a.save_to });
+    }
+    return json(state);
+}));
+export async function runMcp() {
+    await server.connect(new StdioServerTransport());
+}

package/dist/test/mcp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/mcp.test.js

@@ -0,0 +1,111 @@
+// The MCP server over a real stdio transport, driven by the SDK's own
+// client. Offline half: the server starts, lists its tools, refuses a
+// tool call without a key as a TOOL error (not a crash), and rejects a
+// bad enum at the schema. Online half (HARMAR_API_KEY + HARMAR_API_URL
+// set): balance, a transcript, subtitles, and a 404 as a tool error.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+const CLI = new URL("../cli.js", import.meta.url).pathname;
+async function connect(env) {
+    const c = new Client({ name: "harmar-test", version: "0" });
+    const clean = {};
+    for (const [k, v] of Object.entries(env))
+        if (v !== undefined)
+            clean[k] = v;
+    await c.connect(new StdioClientTransport({ command: process.execPath, args: [CLI, "mcp"], env: clean }));
+    return c;
+}
+const textOf = (r) => r.content[0].text;
+test("lists the fourteen tools", async () => {
+    const c = await connect({ PATH: process.env.PATH });
+    const { tools } = await c.listTools();
+    assert.deepEqual(tools.map((t) => t.name).sort(), [
+        "harmar_balance",
+        "harmar_delete_style_preset",
+        "harmar_delete_transcript",
+        "harmar_export",
+        "harmar_get_export",
+        "harmar_get_subtitles",
+        "harmar_get_transcript",
+        "harmar_languages",
+        "harmar_list_style_presets",
+        "harmar_list_styles",
+        "harmar_pricing",
+        "harmar_save_style",
+        "harmar_transcribe",
+        "harmar_usage",
+    ]);
+    await c.close();
+});
+test("a missing key is a tool error, not a crash", async () => {
+    const c = await connect({ PATH: process.env.PATH, HARMAR_API_KEY: undefined });
+    const r = await c.callTool({ name: "harmar_balance", arguments: {} });
+    assert.equal(r.isError, true);
+    assert.match(textOf(r), /missing_api_key/);
+    // The server is still alive after the error.
+    const { tools } = await c.listTools();
+    assert.equal(tools.length, 14);
+    await c.close();
+});
+test("a bad enum is rejected by the schema", async () => {
+    const c = await connect({ PATH: process.env.PATH, HARMAR_API_KEY: "hk_live_x" });
+    const r = await c
+        .callTool({ name: "harmar_get_subtitles", arguments: { id: "x", format: "pdf" } })
+        .catch((e) => ({ isError: true, content: [{ type: "text", text: e.message }] }));
+    assert.equal(r.isError, true);
+    assert.match(textOf(r), /format|invalid|enum/i);
+    await c.close();
+});
+const online = Boolean(process.env.HARMAR_API_KEY && process.env.HARMAR_API_URL);
+test("online: balance, transcript, subtitles, 404", { skip: !online && "set HARMAR_API_KEY + HARMAR_API_URL" }, async () => {
+    const c = await connect(process.env);
+    const bal = JSON.parse(textOf(await c.callTool({ name: "harmar_balance", arguments: {} })));
+    assert.equal(typeof bal.seconds_remaining, "number");
+    const notFound = await c.callTool({
+        name: "harmar_get_transcript",
+        arguments: { id: "00000000-0000-0000-0000-000000000000" },
+    });
+    assert.equal(notFound.isError, true);
+    assert.match(textOf(notFound), /not_found/);
+    const styles = JSON.parse(textOf(await c.callTool({ name: "harmar_list_styles", arguments: {} })));
+    assert.equal(styles.presets.length, 7);
+    assert.ok(styles.fonts.some((f) => f.key === "noto" && f.languages.includes("hy")));
+    assert.ok("accentColor" in styles.fields);
+    const presets = JSON.parse(textOf(await c.callTool({ name: "harmar_list_style_presets", arguments: {} })));
+    assert.ok(Array.isArray(presets));
+    const rejected = await c.callTool({ name: "harmar_save_style", arguments: { name: "x", style: { preset: "pill", accent_color: "#fff" } } });
+    assert.equal(rejected.isError, true, "unknown style field must be a tool error");
+    assert.match(textOf(rejected), /invalid_style/);
+    // A real export through the MCP tool, saved to disk. Needs a transcript
+    // that was submitted with keep_media (HARMAR_TEST_EXPORT_ID).
+    const exportId = process.env.HARMAR_TEST_EXPORT_ID;
+    if (exportId) {
+        const { mkdtempSync, statSync } = await import("node:fs");
+        const { tmpdir } = await import("node:os");
+        const { join } = await import("node:path");
+        const out = join(mkdtempSync(join(tmpdir(), "harmar-sdk-")), "captioned.mp4");
+        const r = await c.callTool({
+            name: "harmar_export",
+            arguments: { id: exportId, style: { preset: "popin", font: "noto", accentColor: "#D4F25A" }, save_to: out, timeout_seconds: 600 },
+        });
+        assert.notEqual(r.isError, true, textOf(r));
+        const state = JSON.parse(textOf(r));
+        assert.equal(state.status, "completed");
+        assert.equal(state.file, out);
+        assert.ok(statSync(out).size > 10_000, "mp4 written");
+    }
+    const id = process.env.HARMAR_TEST_TRANSCRIPT_ID;
+    if (id) {
+        const tr = JSON.parse(textOf(await c.callTool({ name: "harmar_get_transcript", arguments: { id } })));
+        assert.equal(tr.status, "completed");
+        assert.ok(!("words" in tr), "words omitted by default");
+        assert.equal(typeof tr.word_count, "number");
+        const full = JSON.parse(textOf(await c.callTool({ name: "harmar_get_transcript", arguments: { id, include_words: true } })));
+        assert.equal(full.words.length, tr.word_count);
+        const srt = textOf(await c.callTool({ name: "harmar_get_subtitles", arguments: { id, format: "srt" } }));
+        assert.match(srt, /^1\r?\n\d\d:\d\d:\d\d,\d\d\d --> /);
+    }
+    await c.close();
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "harmar-ai",
+  "version": "0.1.0",
+  "description": "Harmar subtitle API for agents and scripts — CLI, MCP server and typed client. Word-timed transcripts, SRT/VTT and styled captioned videos for Armenian, Russian, English and 50+ more languages, code-switching included.",
+  "license": "MIT",
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "bin": { "harmar": "./dist/cli.js" },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "files": ["dist", "skills", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "test": "node --test dist/test/*.test.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": ["subtitles", "transcription", "srt", "vtt", "armenian", "mcp", "cli", "speech-to-text", "captions"],
+  "repository": { "type": "git", "url": "https://github.com/fulfilledbyai/harmar-sdk.git" },
+  "homepage": "https://harmar.ai/developers",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/skills/harmar/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: harmar
+description: Transcribe audio/video, and produce styled captioned videos (burned-in subtitles as MP4) or SRT/VTT files with the Harmar API. Use when asked to transcribe, caption or subtitle a media file, to make a "video with captions" in a specific look (font, colours, pill/karaoke style), to save a subtitle style and reuse it, or for "what language is this recording" — especially Armenian, Russian, English and code-switched speech, plus 50+ other languages.
+---
+
+# Harmar — subtitles from speech, captioned videos from subtitles
+
+Harmar (harmar.ai) transcribes speech into word-level timestamps, writes
+SRT/VTT, and burns styled captions into the video (MP4, no watermark, up to
+1080p). It is the reference engine for Armenian and for Armenian/Russian/
+English code-switching, and serves 50+ other languages. Prepaid credits,
+charged per second of media for a transcript and again for an export,
+refunded on failure. 10 free minutes on the first API key.
+
+## Setup (once)
+
+1. Key: https://harmar.ai/app/api → create an API key (`hk_live_…`).
+2. `export HARMAR_API_KEY=hk_live_…`
+3. The CLI runs without install: `npx -y harmar-ai <command>`.
+
+If `HARMAR_API_KEY` is unset, stop and ask the user for it — do not guess.
+
+## Commands
+
+```bash
+# Armenian speech (the default) → JSON with text, segments and every word's start/end
+npx -y harmar-ai transcribe video.mp4
+
+# Don't know the language? Let it identify the language from the audio.
+npx -y harmar-ai transcribe video.mp4 --lang auto --srt --out video.srt
+
+# Russian speech, plus an Armenian subtitle track (translation is free)
+npx -y harmar-ai transcribe talk.mp4 --lang ru --translate-to hy --vtt --out talk.hy.vtt
+
+# Long file: submit, then poll
+npx -y harmar-ai transcribe long.mp4 --no-wait        # prints {"id": …}
+npx -y harmar-ai status <id>                          # progress 0–100, then the transcript
+npx -y harmar-ai srt <id> --out long.srt
+
+npx -y harmar-ai languages     # what --lang / --translate-to accept, live
+npx -y harmar-ai balance       # minutes left
+```
+
+`--lang` takes an ISO code (`hy`, `ru`, `en`, `kk`, `ka`, `uk`, …) or `auto`.
+Output is JSON unless `--srt`, `--vtt` or `--text` is given. Progress goes to
+stderr; the result goes to stdout or `--out`.
+
+## Captioned video (styled export)
+
+The video is only exportable if the transcript was made with `--keep-media`
+(or `--export`, which implies it) — by default the source is deleted the
+moment the transcript exists.
+
+```bash
+# 1. see what a style can be: presets, fonts + the languages each renders, fields
+npx -y harmar-ai styles
+
+# 2. save the look once, by name — then every export uses exactly it
+npx -y harmar-ai save-style "Brand" --style '{"preset":"pill","font":"montserrat","accentColor":"#D4F25A","bgOpacity":0.6,"posY":78}'
+#    → prints the preset id
+
+# 3a. one shot: transcribe + export
+npx -y harmar-ai transcribe reel.mp4 --lang auto --export --preset <preset id> --out reel-captioned.mp4
+
+# 3b. or export an existing transcript (made with --keep-media)
+npx -y harmar-ai export <id> --preset <preset id> --out reel-captioned.mp4
+npx -y harmar-ai export <id> --style-file brand.json --track en --platform instagram --out out.mp4
+
+npx -y harmar-ai presets            # saved styles
+npx -y harmar-ai export-status <id> # queued / rendering N% / completed (download_url) / failed
+```
+
+Rules the agent should follow:
+- **Ask the user for the look if none was given** (colours, font, pill vs
+  karaoke, position), or use the platform defaults from `harmar styles --json`.
+- **Check the font renders the language**: `fonts[].languages` in the
+  catalog. A font without the track's language falls back to Noto.
+- **Save the style as a preset** when the user will want the same look again,
+  and export by `--preset <id>` — that is the reliable way to reproduce it.
+- `--track` picks which subtitle track to burn: the source language
+  (default) or the `--translate-to` language.
+- One export runs at a time per account; a second request answers
+  `too_many_exports` — wait, then retry.
+- Exit 1 with `media_purged` means the transcript was made without
+  `--keep-media`: transcribe the file again with `--keep-media` (or `--export`).
+
+## Options that change the transcript
+
+| Flag | Effect |
+|---|---|
+| `--timestamps word\|segment\|none` | granularity in the JSON (default word) |
+| `--no-punctuation` | strip punctuation |
+| `--no-speakers` | drop dialogue dashes and speaker ids |
+| `--lyrics include` | keep sung lines (excluded by default) |
+| `--script file.txt` | you already have the exact words — align them, no transcription |
+| `--webhook https://…` | POST on completion, `Harmar-Signature` HMAC header |
+
+## Limits and errors
+
+- Formats: MP4, MOV, WebM, M4A, MP3, WAV. Up to 60 minutes per file, 5 GB.
+- Exit 1 with `insufficient_credits` carries `seconds_needed` and
+  `seconds_available` — tell the user how many minutes to buy at
+  https://harmar.ai/app/api; do not retry.
+- Exit 3 means the wait timed out; the job is still running — `harmar status <id>`
+  (or `harmar export-status <id>` for an export).
+- A failed job refunds its charge automatically.
+- Transcripts and media are purged after the retention window; `harmar delete <id>` purges now.
+
+## Raw HTTP (if the CLI can't be run)
+
+Base `https://api.harmar.ai`, header `Authorization: Bearer $HARMAR_API_KEY`.
+
+```bash
+# 1. get a presigned upload
+curl -s -X POST https://api.harmar.ai/v1/uploads -H "Authorization: Bearer $HARMAR_API_KEY" \
+  -H 'Content-Type: application/json' -d '{"filename":"video.mp4","file_size":12345678}'
+# → {"media_id":…,"upload_url":…,"content_type":"video/mp4"}
+
+# 2. PUT the bytes (Content-Type must match)
+curl -s -X PUT "$UPLOAD_URL" -H 'Content-Type: video/mp4' --data-binary @video.mp4
+
+# 3. submit
+curl -s -X POST https://api.harmar.ai/v1/transcripts -H "Authorization: Bearer $HARMAR_API_KEY" \
+  -H 'Content-Type: application/json' -d '{"media_id":"…","source_lang":"auto"}'
+# → 202 {"id":…,"status":"processing","seconds_charged":…}
+
+# 4. poll, then fetch
+curl -s https://api.harmar.ai/v1/transcripts/$ID -H "Authorization: Bearer $HARMAR_API_KEY"
+curl -s https://api.harmar.ai/v1/transcripts/$ID/srt -H "Authorization: Bearer $HARMAR_API_KEY"
+
+# 5. styled export (the transcript must have been submitted with "keep_media": true)
+curl -s https://api.harmar.ai/v1/styles -H "Authorization: Bearer $HARMAR_API_KEY"
+curl -s -X POST https://api.harmar.ai/v1/transcripts/$ID/export -H "Authorization: Bearer $HARMAR_API_KEY" \
+  -H 'Content-Type: application/json' -d '{"style":{"preset":"pill","font":"montserrat","accentColor":"#D4F25A"}}'
+curl -s https://api.harmar.ai/v1/transcripts/$ID/export -H "Authorization: Bearer $HARMAR_API_KEY"
+# → {"status":"completed","download_url":"https://…"}  (signed, 1 hour)
+```
+
+Full reference: https://harmar.ai/developers