LLM Integration Guide

1. Purpose of this page

This page tells a large language model (LLM) or AI coding agent how to write code that uses QuickTranscript, either through the REST API or through the hosted MCP (Model Context Protocol) server. It explains how to transcribe and summarize audio or video files, and what the service does not do. The machine-readable schema at /openapi.json describes the same REST contract. It does not describe the MCP tools: MCP clients discover tool schemas with tools/list (see section 9). This page adds workflow rules, gotchas, and complete examples.

REST base URL: https://quicktranscript.app. MCP endpoint: https://quicktranscript.app/mcp/.

2. Rules for the LLM

1. Authenticate every REST and MCP request with the X-API-Key header. Keys start with vdz_. Users create keys at /api-keys. Never invent a key.
2. Read the key from an environment variable (for example QUICKTRANSCRIPT_API_KEY). Never hard-code it, log it, or include it in commits.
3. Transcription runs as an asynchronous job. With REST, submit with POST /api/transcriptions (or, for files over 95 MB, the direct upload), then poll GET /api/transcriptions/{task_id} until status is complete or failed. With MCP, call transcribe_url (or, for a local file, create_upload_url and upload the file with the returned token), then get_transcription_status (see section 9).
4. For POST /api/transcriptions, send the request body as form fields: multipart/form-data (required for file uploads) or application/x-www-form-urlencoded. Do not send a JSON body. A JSON {"file_url": ...} body is ignored and returns 400 No file or file_url supplied. The direct-upload endpoints /api/transcriptions/uploads/init, /complete, and /abort take JSON. This rule does not apply to MCP: the MCP SDK sends JSON-RPC for you, and tools/list returns the tool schemas.
5. A file upload must declare an audio/* or video/* content type. Otherwise the API returns 400 Invalid file type. Set it explicitly: tools such as curl send application/octet-stream for extensions they don't recognize, such as .m4a.
6. Poll every 5–10 seconds and stop after a timeout you choose. Processing time grows with media length.
7. Use only the REST endpoints in the table below or the MCP endpoint in section 9. Do not call browser routes such as /upload, /process-url, /task-status/…, or /history. Those return HTML, not JSON.
8. summary_html is HTML. Render it as HTML or convert it to text. Do not show it to users as raw markup.

3. Endpoint reference

4. Job lifecycle

status moves through these values:

pending → processing → transcribing → summarizing (only if summarize=true) → complete
                                                                           ↘ failed (from any step)

• Stop polling at complete or failed. Treat every other value as still running.
• status_message is a short human-readable progress message, for example "Transcribing audio...".
• A failed job includes error_message (a user-facing reason such as "There was an issue reading the uploaded file.") and error_type (file_error, download_error, prohibited_content, insufficient_credits, or processing_error). Show error_message to the user. Both fields are null unless status is failed.
• Credits are deducted only when a job completes. Failed jobs cost nothing.
• If transcription succeeds but summarization fails, the job still ends as complete. In that case summary_html contains a paragraph starting with (Summary could not be generated.

5. Response schemas

Status object: GET /api/transcriptions/{task_id}

{
  "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "transcribing",
  "status_message": "Transcribing audio...",
  "error_message": null,
  "error_type": null,
  "result": null
}

A failed job:

{
  "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "failed",
  "status_message": "Processing failed.",
  "error_message": "The uploaded file appears to be corrupted or in an unsupported format.",
  "error_type": "processing_error",
  "result": null
}

When status is complete, result holds a result object.

Result object

{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "original_filename": "meeting.mp3",
  "completed_at": "2026-09-24T05:56:00.357729+00:00",
  "duration_seconds": 3038.7,
  "transcription": [
    {"timestamp": "[00:00]", "text": "Okay, let's get started."},
    {"timestamp": "[20:00]", "text": "Moving on to the quarterly results."},
    {"timestamp": "[01:00:00]", "text": "Thanks everyone."}
  ],
  "summary_html": "<p>The meeting covered the <strong>quarterly results</strong>.</p>",
  "final_credit_cost": 2,
  "total_tokens": null
}

6. Limits and credits

• Maximum file size: 95 MB for a multipart upload to POST /api/transcriptions (request bodies pass through a proxy that rejects bodies over 100 MB), and 500 MB for a direct upload or a URL download. Larger files return 413.
• Cost: max(1, ceil(file_size_MB / 30)) credits, estimated from the file size at submission time. The balance is checked before the job is accepted.
• URL downloads must return HTTP 200 with an audio/*, video/*, or application/octet-stream content type within 60 seconds. Share links from Google Drive, Dropbox, and OneDrive are converted to direct-download links automatically. The file must be public. Private or internal network addresses are rejected.
• Supported media includes common audio and video formats such as MP3, WAV, M4A, FLAC, OGG, WEBM, MP4, MOV, and MKV.

7. Errors

REST errors use the FastAPI shape {"detail": "<message>"}. Validation errors (422) return detail as an array. MCP errors are described in section 9.3.

8. Examples

8.1 curl: verify the key and check credits

export QUICKTRANSCRIPT_API_KEY="vdz_your_api_key"

curl -s https://quicktranscript.app/api/auth/test -H "X-API-Key: $QUICKTRANSCRIPT_API_KEY"
# {"authenticated":true,"user_email":null}

curl -s https://quicktranscript.app/api/credits -H "X-API-Key: $QUICKTRANSCRIPT_API_KEY"
# {"credits":12}

8.2 curl: upload a file with an explicit content type

curl -s -X POST https://quicktranscript.app/api/transcriptions \
  -H "X-API-Key: $QUICKTRANSCRIPT_API_KEY" \
  -F "[email protected];type=audio/mp4"
# {"task_id":"a1b2c3d4-e5f6-7890-1234-567890abcdef","status":"pending"}

8.3 curl: transcribe from a URL without a summary

curl -s -X POST "https://quicktranscript.app/api/transcriptions?summarize=false" \
  -H "X-API-Key: $QUICKTRANSCRIPT_API_KEY" \
  -F "file_url=https://www.dropbox.com/s/abc123/podcast.mp3?dl=0"

8.4 bash: poll until the job finishes (requires jq)

TASK_ID="a1b2c3d4-e5f6-7890-1234-567890abcdef"
while true; do
  RESPONSE=$(curl -s "https://quicktranscript.app/api/transcriptions/$TASK_ID" \
    -H "X-API-Key: $QUICKTRANSCRIPT_API_KEY")
  STATUS=$(echo "$RESPONSE" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in
    complete) echo "$RESPONSE" | jq -r '.result.transcription[] | "\(.timestamp) \(.text)"'; break ;;
    failed)   echo "$RESPONSE" | jq -r .error_message; exit 1 ;;
  esac
  sleep 5
done

8.5 Python (httpx): complete client

import mimetypes
import os
import time
from pathlib import Path

import httpx

BASE_URL = "https://quicktranscript.app"
TERMINAL_STATUSES = {"complete", "failed"}


class QuickTranscriptError(RuntimeError):
    pass


def _client() -> httpx.Client:
    api_key = os.environ["QUICKTRANSCRIPT_API_KEY"]
    return httpx.Client(
        base_url=BASE_URL, headers={"X-API-Key": api_key}, timeout=120
    )


def _check(response: httpx.Response) -> dict:
    if response.is_error:
        detail = response.json().get("detail", response.text)
        raise QuickTranscriptError(f"{response.status_code}: {detail}")
    return response.json()


def submit_file(client: httpx.Client, path: Path, summarize: bool = True) -> str:
    content_type = mimetypes.guess_type(path.name)[0] or "audio/mpeg"
    with path.open("rb") as media:
        response = client.post(
            "/api/transcriptions",
            params={"summarize": str(summarize).lower()},
            files={"file": (path.name, media, content_type)},
        )
    return _check(response)["task_id"]


def submit_url(client: httpx.Client, url: str, summarize: bool = True) -> str:
    response = client.post(
        "/api/transcriptions",
        params={"summarize": str(summarize).lower()},
        data={"file_url": url},  # form field, NOT json=
    )
    return _check(response)["task_id"]


def wait_for_result(
    client: httpx.Client, task_id: str, interval: float = 5, timeout: float = 3600
) -> dict:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        job = _check(client.get(f"/api/transcriptions/{task_id}"))
        if job["status"] == "complete":
            return job["result"]
        if job["status"] == "failed":
            raise QuickTranscriptError(f"Job {task_id} failed: {job['error_message']}")
        time.sleep(interval)
    raise TimeoutError(f"Job {task_id} did not finish within {timeout}s")


if __name__ == "__main__":
    with _client() as client:
        print("credits:", _check(client.get("/api/credits"))["credits"])
        task_id = submit_file(client, Path("meeting.mp3"))
        result = wait_for_result(client, task_id)
        full_text = "\n".join(
            f"{segment['timestamp']} {segment['text']}"
            for segment in result["transcription"] or []
        )
        print(full_text)
        print(result["summary_html"])

8.6 JavaScript (Node.js 20+, built-in fetch)

import { openAsBlob } from "node:fs";
import { basename } from "node:path";

const BASE_URL = "https://quicktranscript.app";
const headers = { "X-API-Key": process.env.QUICKTRANSCRIPT_API_KEY };

async function check(response) {
  const body = await response.json();
  if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(body.detail)}`);
  return body;
}

export async function submitFile(path, { summarize = true, type = "audio/mpeg" } = {}) {
  const form = new FormData();
  form.append("file", await openAsBlob(path, { type }), basename(path));
  const response = await fetch(`${BASE_URL}/api/transcriptions?summarize=${summarize}`, {
    method: "POST",
    headers, // do NOT set Content-Type; fetch adds the multipart boundary
    body: form,
  });
  return (await check(response)).task_id;
}

export async function submitUrl(url, { summarize = true } = {}) {
  const form = new FormData();
  form.append("file_url", url);
  const response = await fetch(`${BASE_URL}/api/transcriptions?summarize=${summarize}`, {
    method: "POST",
    headers,
    body: form,
  });
  return (await check(response)).task_id;
}

export async function waitForResult(taskId, { intervalMs = 5000, timeoutMs = 3_600_000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const job = await check(await fetch(`${BASE_URL}/api/transcriptions/${taskId}`, { headers }));
    if (job.status === "complete") return job.result;
    if (job.status === "failed") throw new Error(`Job ${taskId} failed: ${job.error_message}`);
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
  throw new Error(`Job ${taskId} timed out`);
}

const taskId = await submitFile("meeting.mp3");
const result = await waitForResult(taskId);
console.log(result.transcription.map((s) => `${s.timestamp} ${s.text}`).join("\n"));

8.7 Python: polling trigger for new completed jobs (Zapier-style)

import os
import time

import httpx

with httpx.Client(
    base_url="https://quicktranscript.app",
    headers={"X-API-Key": os.environ["QUICKTRANSCRIPT_API_KEY"]},
    timeout=30,
) as client:
    while True:
        response = client.get("/api/transcriptions/completed", params={"limit": 50})
        response.raise_for_status()
        for job in response.json():  # each job is returned exactly once
            print(job["task_id"], job["original_filename"])
            # Persist the job before doing anything else: it will not be returned again.
        time.sleep(60)

8.8 bash: direct upload of a file over 95 MB (requires jq)

The file goes straight to storage in parts. init checks the type, size, and credits and returns one presigned URL per part (valid for 12 hours). Part N is bytes (N-1) × part_size up to N × part_size; each URL accepts exactly that length. complete must follow within 13 hours, with the same credentials (410 when expired). Calling it again returns the same task_id, so it is safe to retry after a lost response, a 500, or a 503. An account may start 100 uploads per hour (429 with Retry-After afterwards). Call /api/transcriptions/uploads/abort with {"upload_id"} to give up.

FILE=lecture.mp4; TYPE=video/mp4
SIZE=$(wc -c < "$FILE" | tr -d ' ')
PLAN=$(curl -sS -X POST https://quicktranscript.app/api/transcriptions/uploads/init \
  -H "X-API-Key: $QUICKTRANSCRIPT_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg f "$FILE" --arg t "$TYPE" --argjson s "$SIZE" '{filename: $f, size: $s, content_type: $t}')")
UPLOAD_ID=$(jq -r .upload_id <<< "$PLAN"); PART_SIZE=$(jq -r .part_size <<< "$PLAN")
PARTS='[]'
for N in $(jq -r '.parts[].part_number' <<< "$PLAN"); do
  URL=$(jq -r ".parts[$((N - 1))].url" <<< "$PLAN")
  dd if="$FILE" bs="$PART_SIZE" skip=$((N - 1)) count=1 2>/dev/null > part.bin
  ETAG=$(curl -sS -X PUT -T part.bin -D - -o /dev/null "$URL" | tr -d '\r' | awk 'tolower($1) == "etag:" {print $2}')
  PARTS=$(jq --argjson n "$N" --arg e "$ETAG" '. + [{PartNumber: $n, ETag: $e}]' <<< "$PARTS")
done
rm -f part.bin
curl -sS -X POST https://quicktranscript.app/api/transcriptions/uploads/complete \
  -H "X-API-Key: $QUICKTRANSCRIPT_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg id "$UPLOAD_ID" --argjson parts "$PARTS" '{upload_id: $id, parts: $parts}')"
# {"task_id":"a1b2c3d4-e5f6-7890-1234-567890abcdef","status":"pending"}

9. Remote MCP server

QuickTranscript also runs a hosted MCP (Model Context Protocol) server. MCP clients and agents can call it as tools instead of writing REST code. It uses the same API keys, credits, URL downloader, and job records as the REST API.

Client compatibility

Client capabilities and menu names change; check your client's documentation for how it sends custom headers or bearer tokens, or how it adds remote MCP servers (Claude, ChatGPT). Connector availability depends on your plan, workspace, and admin policies. QuickTranscript is an official connector in the Claude connector directory; it is not listed in ChatGPT's app directory.

OAuth connections (claude.ai, ChatGPT)

Clients that only support OAuth use the same URL, https://quicktranscript.app/mcp/. The client discovers the server's OAuth settings, registers itself, and opens a QuickTranscript approval page in your browser:

1. The page shows the client's name, which the client declares itself and is not verified, and the address it returns to. Check both.
2. Paste an existing QuickTranscript API key (create one at /api-keys) and click Approve, or click Deny. You don't sign in with your QuickTranscript account on this page.
3. The client then calls the MCP tools with an OAuth access token. The key itself is never sent to the client.

Approving lets the client, on behalf of the key's account:

• submit media-URL transcriptions, which spend your credits;
• read the status and results of your account's tasks;
• read your credit balance;
• only if you tick Also allow starting meeting bots: start, check, and stop meeting bots, which record other people and spend your credits.

The meeting opt-in belongs to the connection, not to the OAuth scope, so it survives token refresh. Connections approved without it (including every connection approved before the option existed) cannot use the meeting tools; reconnect to add it.

Access tokens last 1 hour and the client refreshes them automatically. Refresh tokens rotate on every use; reusing an old refresh token revokes the whole connection. A connection expires 30 days after approval; then reconnect and approve again.

To disconnect, revoke or delete the API key at /api-keys. Every OAuth connection approved with that key stops working immediately. Create a dedicated API key for each connector so you can disconnect one without affecting your other integrations. Clients can also revoke their own connection at /revoke.

The vendor connects from its own cloud, not from your device, so the MCP server must be reachable over public HTTPS. The hosted server at https://quicktranscript.app/mcp/ meets this requirement.

9.1 Tools

Successful tool results carry the JSON object in structuredContent. The size limits are the same as the REST API: 500 MB for URL downloads and direct uploads, 95 MB for multipart uploads to upload_url. Larger files fail with a 413.

9.2 Limitations

• Meeting-bot tools need an OAuth connection approved with the meeting opt-in. Clients that send an API key directly (X-API-Key or bearer key) cannot start meeting bots, and neither can the REST API.
• Only public audio or video file URLs are accepted. Share links from Google Drive, Dropbox, and OneDrive work as in REST; private or internal network addresses are rejected.
• transcribe_url does not ingest YouTube web pages; the URL must point to a media file.
• The MCP client must send your API key as a custom X-API-Key header or as a bearer token on every request, or connect with OAuth.
• To transcribe a local file, call create_upload_url. Up to 95 MB, POST the file to the returned upload_url as multipart field file with the returned upload_token in the X-Upload-Token header. Larger files (up to 500 MB): call init_url with the token, PUT the parts, then call complete_url, as in the direct upload. Then poll the returned task_id with get_transcription_status. This needs an agent that can run shell commands or send HTTP requests (Claude Code, Codex, Cursor); chat-only apps such as claude.ai or ChatGPT need a public URL.

9.3 Errors

MCP failures happen at two levels. HTTP-level failures reject the request before any MCP message is processed:

Tool failures are normal MCP tool results with isError: true. Their text content is prefixed by the MCP SDK, for example:

Error executing tool transcribe_url: 402: Insufficient credits. Need 1, have 0.

The stable part is <status_code>: <detail> at the end of the text. The codes match the REST error table:

A job that fails during processing is not a tool error: get_transcription_status returns it with status: "failed".

9.4 Python (official MCP SDK): complete client

Install the client dependencies in your uv project with uv add 'mcp>=1.28.1,<2' httpx. Set QUICKTRANSCRIPT_API_KEY to your API key and QUICKTRANSCRIPT_MEDIA_URL to a public media file URL, then run the script with uv run python quicktranscript_mcp.py. The API key header is set on the httpx.AsyncClient passed to streamable_http_client.

import asyncio
import os
import time

import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://quicktranscript.app/mcp/"


def tool_data(result):
    if result.isError:
        message = result.content[0].text if result.content else "unknown error"
        raise RuntimeError(message)
    return result.structuredContent


async def main():
    headers = {"X-API-Key": os.environ["QUICKTRANSCRIPT_API_KEY"]}
    async with httpx.AsyncClient(headers=headers, timeout=120) as client:
        async with streamable_http_client(MCP_URL, http_client=client) as (read, write, _):
            async with ClientSession(read, write) as session:
                await session.initialize()
                tools = await session.list_tools()
                print("Tools:", [tool.name for tool in tools.tools])

                credits = tool_data(await session.call_tool("get_credit_balance", {}))
                print("Credits:", credits["credits"])

                job = tool_data(await session.call_tool(
                    "transcribe_url",
                    {"file_url": os.environ["QUICKTRANSCRIPT_MEDIA_URL"], "summarize": True},
                ))
                task_id = job["task_id"]
                print("Task:", task_id)

                deadline = time.monotonic() + 600
                while True:
                    status = tool_data(await session.call_tool(
                        "get_transcription_status", {"task_id": task_id}
                    ))
                    if status["status"] in ("complete", "failed"):
                        break
                    if time.monotonic() > deadline:
                        raise TimeoutError(f"Task {task_id} still {status['status']}")
                    await asyncio.sleep(5)

                if status["status"] == "failed":
                    print("Failed:", status["error_type"], status["error_message"])
                else:
                    result = status["result"]
                    text = " ".join(seg["text"] for seg in result["transcription"] or [])
                    print("Transcript:", text[:500])
                    print("Summary HTML present:", result["summary_html"] is not None)


asyncio.run(main())

Other MCP clients can connect if they support Streamable HTTP and custom request headers; check your client's documentation for how to set X-API-Key.

10. Short prompt for another agent

Give this summary to another agent that needs to integrate:

QuickTranscript (https://quicktranscript.app). Auth for REST and MCP: header X-API-Key: vdz_… (from env, never hard-code).
REST:
1. POST /api/transcriptions with form fields (multipart for files) and exactly one of: file (audio/* or video/* content type,
   max 95 MB) or file_url (public URL form field; JSON bodies are ignored). Optional query summarize=false.
   Returns 202 {task_id}. Files up to 500 MB: POST JSON {filename, size, content_type, summarize} to
   /api/transcriptions/uploads/init -> {upload_id, part_size, parts: [{part_number, url}]}; PUT each part_size slice to its url
   (keep the ETag header); POST JSON {upload_id, parts: [{PartNumber, ETag}]} to /api/transcriptions/uploads/complete -> 202 {task_id}.
2. Poll GET /api/transcriptions/{task_id} every 5-10 s until status is "complete" or "failed".
3. On complete, read result.transcription (list of {timestamp "[MM:SS]"/"[HH:MM:SS]", text}) and result.summary_html (HTML or null).
Errors: {"detail": ...}; 401 bad key, 402 no credits, 413 file too large, 400 bad input, 404/403 unknown or foreign task.
Balance: GET /api/credits. Key check: GET /api/auth/test. Schema: /openapi.json (REST only).
MCP: https://quicktranscript.app/mcp/ (trailing slash), Streamable HTTP, API key on every request as X-API-Key or Authorization: Bearer.
OAuth-only clients (claude.ai official connector at https://claude.ai/directory/quicktranscript-app, claude.ai custom connectors, ChatGPT connectors) use the same URL: OAuth 2.1 + PKCE S256 + Dynamic Client Registration,
scope mcp, discovery at /.well-known/oauth-protected-resource; the user approves by pasting an API key. Access token 1 h, rotating refresh,
reconnect after 30 days; revoking the source API key disconnects. Also works with Claude Code, Claude API, OpenAI Responses API, MCP SDKs.
Tools (schemas via tools/list): transcribe_url(file_url, summarize=true) -> {task_id, status}; public media URLs only, spends credits,
don't auto-retry. create_upload_url(summarize=true) -> {upload_url, init_url, complete_url, abort_url, upload_token, expires_at,
max_upload_mb, max_multipart_upload_mb, curl_example}; free. Within 15 min, with header X-Upload-Token: upload_token, either POST the
local file to upload_url as multipart field "file" with audio/* or video/* type (up to max_multipart_upload_mb), or POST the init JSON to
init_url and finish like the REST direct upload via complete_url (no token needed there) -> 202 {task_id, status};
token single-use even on 400/402/413, else 404.
get_transcription_status(task_id) -> same status object as REST; poll every 5-10 s. get_credit_balance() -> {credits}.
Tool errors: isError=true, text ends with "<status_code>: <detail>". HTTP 401 = bad key or token. Local files: create_upload_url, upload, then poll.