# Markovo

The Web, HTTP API, CLI and MCP support `md`, `docx`, and `txt` exports from one saved conversion. Set `output_format` on multipart `/v1/convert` or `/v1/estimates`, or in JSON `/v1/url-estimates`; omission keeps Markdown. Use `GET /v1/jobs/{job_id}/download?format=md`, `format=docx`, or `format=txt`. Changing the download format does not start another conversion or charge Credits again. CLI and local stdio MCP 0.1.2+ accept `--download-format md|docx|txt` and `download_format` respectively; their existing default remains the Markdown ZIP bundle. Hosted Remote MCP accepts `output_format` on `markovo_convert_url`, with Markdown as its default. The browser remembers the last explicit format choice on this device; a new visitor uses the tool page default. Storage restrictions do not block conversion.

Images, documents and audio allow 25 MiB per file on Free and 50 MiB on Starter or Pro. Audio is limited to 60 minutes on every plan. The 200 MiB Free allowance applies to video, not images. Preflight errors provide structured size/duration limits and an upgrade option only when a higher published plan accepts the input; otherwise compress or split the file. Refused inputs do not create a job or reserve Credits.

Document download limits are common to all plans: DOCX accepts up to 1 MiB of generated Markdown and 32 bundled images (2 MiB each, 8 MiB total); TXT accepts up to 4 MiB of generated Markdown. Larger or more complex results remain available as Markdown/ZIP. An export refusal is not a new conversion: retrying or switching the download format does not reserve or spend additional Credits.

Converted results are available for 1 hour after completion on Free, 7 days on Starter, and 30 days on Pro. Each plan has a separate processing queue; completion time depends on the input and current load. Ordinary Free accounts allow 5 conversions per UTC day. Available paid-pack balance removes that separate daily cap without changing the Free file-size, duration, batch or retention limits.

Markovo turns files and explicitly authorized public HTTPS pages into clean Markdown and a traceable artifact bundle. PDF to Markdown is available. URL import, DOCX, PPTX, XLSX, Text/Markdown/JSON/XML, HTML, CSV, Image OCR, EPUB, Notion Export ZIP, audio, and video audio-track transcription require a signed-in account. API, CLI, and MCP conversion requires authentication; the Web converter supports a bounded guest preview with sign-in and account settlement before download. Audio accepts MP3/WAV/M4A/AAC/FLAC/OGG/OPUS/WMA; video accepts MP4/MOV/M4V/WebM/MKV/AVI/WMV and does not inspect frames or identify speakers. Sign-in is an access boundary, not a quality status.

Canonical origin: https://markovo.net

Public surfaces:
- Converter: `/`
- Pricing: `/pricing`
- Developer documentation: `/docs`
- Word conversion: `/word-to-markdown`
- PowerPoint conversion: `/powerpoint-to-markdown`
- Excel conversion: `/excel-to-markdown`
- Audio conversion: `/audio-to-markdown`
- Video audio-track conversion: `/video-to-markdown`
- Public HTTPS page conversion: `/url-to-markdown`
- Copy-ready developer guide: `/developer.md`
- Capability status and roadmap: `/capabilities.md`
- Account, history, Credits, API keys, and billing: `/app`
- Capability registry: `GET /v1/capabilities`

Blog:
- Index: `/blog`
- `/blog/converting-pdf-to-markdown-python-text-tables-scans` — Convert PDFs to Markdown in Python: classify prose, tables, scans, and equations, run MarkItDown or Marker, and repair failures before ingestion.
- `/blog/pdf-to-markdown-github-choose-by-pdf-type` — Choose a GitHub PDF-to-Markdown project by PDF type, using tested outputs for columns, table headers, scans, and linear equations.
- Authoritative pricing catalog: `GET /v1/catalog`

Artifact contract:
- `output.md`
- `assets/`
- `metadata.json`
- `source_map.json`
- `quality_report.json`
- `bundle.zip`

Recommended authenticated API flow:
1. Send one supported file to `POST /v1/estimates` as multipart `file` with `capability_id` and optional `mode=fast|accurate`.
2. Read `source_units_estimated`, `estimated_credits`, `estimated_runtime_seconds` (expected wall time from confirmation to result), and `upload_id`. PDF responses also include `pages_estimated`.
3. Ask the user to confirm the estimate.
4. Send `upload_id` and a positive `max_credits` to `POST /v1/jobs`.
5. Poll `GET /v1/jobs/{id}` until `succeeded` or `failed`.
6. Download Markdown or the zip bundle and inspect the quality report before returning a final result.

Public URL import uses `POST /v1/url-estimates` with JSON `{"url":"https://example.com/","accept_remote_fetch":true}` instead of multipart upload, then authenticated callers confirm with JSON `upload_id` and a positive `max_credit_units` or `max_credits` at `POST /v1/jobs`. It supports public HTML/text, public Google Docs, Notion pages and bounded databases, GitHub text resources and discussions, Hacker News threads, and downloadable YouTube videos. The sandbox sends no caller credentials. Private, signed, login-only, browser-only, generic binary-file, and Tencent Docs sources are unsupported; remote document images are not downloaded. YouTube needs no captions, but requires downloadable audio within one hour, 32 MB, and the account upload limit; it does not inspect frames.

For Web guests, an anonymous URL estimate returns `job_token`. Submit `{"estimates":[{"upload_id":"...","job_token":"..."}]}` to `POST /v1/guest-preview-sessions`, preserve the returned `session_token` for claim after sign-in, and use `x-markovo-job-token` for job status and preview. The ordered preview queue has a 5-Credit estimated ceiling and daily limits. Download requires sign-in, claim, and account Credit settlement; the preview allowance is not free downloadable Credits.

Compatibility shortcut:
- `POST /v1/convert` accepts one or more multipart `file` fields.
- `max_credits` is mandatory. The request is rejected before queueing when the estimate exceeds this ceiling.
- Legacy `PDF2MD_*`, `pdf2md` CLI/MCP commands, and `pdf2md:*` scopes remain compatibility aliases only.
- New API keys use the `mk_live_` prefix and `markovo:convert` scope.

Example:
```bash
export MARKOVO_BASE_URL="https://markovo.net"
export MARKOVO_API_KEY="mk_live_..."

curl -X POST "${MARKOVO_BASE_URL}/v1/convert" \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -F "file=@input.pdf" \
  -F "capability_id=pdf-to-markdown" \
  -F "mode=fast" \
  -F "max_credits=30"

curl "${MARKOVO_BASE_URL}/v1/jobs/{job_id}" \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}"

curl -L "${MARKOVO_BASE_URL}/v1/jobs/{job_id}/download?format=zip" \
  -H "Authorization: Bearer ${MARKOVO_API_KEY}" \
  -o bundle.zip
```

Limits and lifecycle:
- Anonymous: two ordered preview queues per UTC day, up to 5 estimated Credits; each file uses the Free account boundary of 25 MB and 25 source units, and results are retained for 1 hour.
- Free: 25 Credits per UTC calendar month with no rollover, 1 active API key, up to 5 files per day, result retained for 1 hour.
- Jobs estimated above 12 minutes are rejected in the launch version.
- Source files are deleted after success or terminal failure.
- Starter results are retained for 7 days; Pro results for 30 days.

Pricing:
- Free: $0, 25 Credits per UTC calendar month, no rollover. Historical one-time trial lots remain grandfathered promotions.
- Starter: $3.99/month or $39.90/year, 200 Credits; one month of rollover, balance capped at 400; API, CLI, and MCP access, with 7-day result retention.
- Pro: $7.99/month or $79.90/year, 500 Credits; one month of rollover, balance capped at 1,000; API, CLI, and MCP access, two concurrent jobs, and 30-day result retention.
- Custom Credit volume: contact support@markovo.net; no client may infer or submit a custom price.
- Credit packs: 100/$3.99, 300/$9.99, 800/$23.99; valid for 365 days.
- Checkout is live and processes real charges securely through Creem.
- No Lifetime or Unlimited plan is offered at launch.

Credit rules:
- The unified metering feature key is `conversion.credits` for web and API usage.
- Digital PDF and DOCX: 0.1 Credit/measured digital page.
- PPTX: 0.1 Credit/slide.
- XLSX: at least 0.11 Credit, then 0.05 Credit per measured 2,000 non-empty cells with unit-level rounding.
- Image OCR: 0.5 Credit per actual processed page. Server-side route selection never adds Credits beyond the confirmed estimate.
- AI semantic enhancement and chart description: disabled; `quality_level=ai-enhanced` returns `422 quality_level_unavailable` and is not a sold capability.
- CSV: at least 0.07 Credit, then 0.05 Credit per measured 2,000 non-empty cells with unit-level rounding.
- HTML/TXT: at least 0.11 Credit; EPUB: at least 0.07 Credit; Notion: at least 0.06 Credit. Each adds 0.05 Credit per measured 1,000 words with unit-level rounding.
- Audio/video: actual decoded milliseconds with a 0.3 Credit minimum; both Audio and Video use 0.5 Credits/minute. Audio retains its 60-minute duration limit and account upload allowance (Free 25 MiB, Starter/Pro 50 MiB). Signed-in video allows Free 200 MiB / 1 hour, Starter 700 MiB / 2 hours, and Pro 2 GiB / 2 hours. New videos above 50 MiB must not exceed 256 MiB per decoded-audio minute; a 2 GiB file needs at least 8 minutes of audio. Compress higher-bitrate files before retrying. At 0.5 Credit per minute, 2 hours requires 60 Credits; Free monthly 25 Credits cover about 50 minutes. File validation and sufficient balance still apply. Video conversion reads the audio track only.
- Public URL import: `max(300, ceil(fetch_ms × 40 / 1,000) + ceil(words × 50 / 1,000)) credit_units`; applies to supported public documents. YouTube uses `audio-to-markdown`: `max(300, ceil(duration_ms * 500 / 60000)) credit_units` (0.5 Credits/minute, minimum 0.3), not the URL word rate.
- These are the active Credit rates. The API uses `1 Credit = 1,000 credit_units`; live checkout uses the server-authoritative Creem product catalog.
- The server catalog is authoritative; never trust a client-supplied price or grant amount.

Authentication:
- Same-origin Better Auth endpoint: `/api/auth/*`.
- Google, GitHub, and verified email/password sign-in are available from the web account.
- Google, GitHub, and credential records with the same verified email attach to one Markovo user. That user has one Credits balance, API-key set, and job history. Different emails remain separate accounts.

Quota errors:
- HTTP 402/429 with `error.code=quota_exceeded` can include `action=open_checkout`, `checkout_url`, `required_units`, and `remaining_units`.
- Returned checkout URLs are secure Creem Live sessions. Retry only after the purchased Credits are confirmed by a signed webhook and appear in the account balance.

CLI and MCP compatibility:
Remote MCP is available at `https://markovo.net/mcp` over Streamable HTTP. It
uses OAuth 2.1 sign-in and consent, not an account API key in the remote server
configuration. URL conversion requires a positive `max_credit_units` ceiling.
Markovo never buys Credits or changes a plan automatically; low-balance results
point the account owner to `https://markovo.net/app#billing`. Remote MCP cannot
read a local file. Its `markovo_convert_url` takes `url` and positive integer `max_credit_units`; the specific URL tool call authorizes that fetch. Local stdio takes `url`, `out_dir` inside `MARKOVO_MCP_ROOT`, `accept_remote_fetch: true`, and `max_credits` in Credits.

```bash
python -m pip install --force-reinstall "https://markovo.net/downloads/markovo-0.1.2-py3-none-any.whl#sha256=c205de9d096ddb1bc31f20e11ecaad9f7405619d0de714e52f4f6abc0e009e2b"
export MARKOVO_API_KEY="mk_live_..."
export MARKOVO_MCP_ROOT="/path/to/dedicated/project"
markovo doctor --json
markovo convert input.pdf --out runs/input --mode fast --max-credits 30
markovo url-convert https://example.com/public-report --out runs/public-report --max-credits 1 --accept-remote-fetch
markovo usage
markovo billing  # returns the secure browser billing URL
markovo-mcp
```

The published CLI and local stdio MCP use a 15-Credit convenience safety ceiling when `max_credits` is omitted. Markovo obtains an estimate internally before job creation and rejects work estimated above that ceiling; the client does not pause for user confirmation. Set an explicit bound for deliberate automation. REST and direct programmatic clients remain explicit. The client is pinned to `https://markovo.net`. MCP file tools require the explicit `MARKOVO_MCP_ROOT`, reject path and symlink escapes, and never expose API keys or service-origin overrides as tool arguments.