feat(catalog): add Vid Kraken — YouTube video, audio and clip download API

[pkpio]

What this does

Adds Vid Kraken (https://vidkraken.com) as a self-serve API-key provider and catalogs its 8 core operations: server-side YouTube video / audio / trimmed-clip downloads delivered as a CDN file URL (async job protocol, wired with async: descriptors), the video title/duration and audio-track (dubbed language) lookups that pre-flight a download, and the free account/balances read that serves as the probe. The listing is deliberately scoped to downloads and video info.

Files: registry entry (src/treg/oauth_providers.py), src/treg/catalog/vidkraken.yaml, neutral lettermark src/treg/web/logos/vidkraken.svg, the two test-list additions, and the five generated SKILL.md copies regenerated by scripts/build_plugin.py (provider count 70 → 71; test_the_plugin_skill_is_not_stale fails otherwise). No verified: stamps, no example responses, no credential values anywhere in the diff.

Contact: hello@vidkraken.com

Please reach us there to arrange the test credential for live verification. We will hand over a dedicated key with a bandwidth grant large enough for repeated sweeps (a stock free-plan key is capped at 10 lifetime downloads / 50 info lookups / 10 GB).

Eligibility and integration facts

• Self-serve key: sign in with Google at https://vidkraken.com/dashboard; the API key is shown on the dashboard. No sales call.
• Base URL: https://vidkraken.com/api/v2 (the two legacy hostnames in the spec's servers list are aliases of it).
• Auth: Authorization: Bearer <key> header.
• Probe: GET /me — free, no call limit, returns plan + live balances.
• Docs: https://vidkraken.com/docs (per-endpoint pages linked from each row's docs_url).
• Stable OpenAPI 3.1 spec: https://vidkraken.com/openapi.yaml — yes, published; happy to have an extended tier generated from it (the core file already covers every documented path, see the surface map).
• Pricing: https://vidkraken.com/#pricing. No machine-readable rate-card endpoint; GET /me returns balances, not prices.
• Limits: at most 100 downloads queued or in progress per account (429 beyond, not charged). No published per-minute request limit.

Pricing and billing model

Downloads are billed in bandwidth only: the delivered file size, with a 20 MB minimum per download, drawn from the plan's monthly allowance. There is no per-download fee and failures are never charged. The USD figure in the cost blocks is the plan's effective per-GB rate; the catalog lists the Starter rate as the documented price:

plan	monthly	included	effective	overage
Free	$0	10 GB + 10 downloads, lifetime	—	none (hard stop)
Starter	$99	400 GB	$0.25/GB (listed)	$0.50/GB
Growth	$399	2 TB	$0.20/GB	$0.40/GB
Scale	$1,499	10 TB	$0.15/GB	$0.30/GB

• POST /info (both rows) draws 1 "info request" from a per-plan quota (2× the download quota, e.g. 200,000/month on Starter; 50 lifetime on Free). It is a quota counter that is never priced in USD and has no overage, so it is recorded as 1 credit per call with a note. settle semantics: charged on success only.
• Polling routes and GET /me: free.

Bogus-key probe — observed from the wire, 2026-09-10 15:12:47 UTC

GET https://vidkraken.com/api/v2/me   Authorization: Bearer treg-bogus-key-<timestamp>
HTTP 401
{"error":"Invalid API key"}

Also observed (15:08 UTC): no Authorization header → 401 {"error":"Missing API key. Provide it as 'Bearer YOUR_API_KEY'"}; the same bogus key on POST /info → 401 {"error":"Invalid API key"}. A valid key on GET /me → 200 with plan and balances. I did not run treg's POST /connections/token flow locally; the registry entry relies on the default "any ≥400 rejects" rule, which this behavior satisfies.

Vendor self-verification ledger — 2026-09-10 (15:12 UTC sweep)

Every test_request was run live against production on our own Scale-plan account, reading GET /me balances immediately after each call. The meter is balances.bandwidth_mb.used (bandwidth, THE billed meter), balances.info.used (info quota) and balances.download_count.used.

endpoint	HTTP	test target	catalog price	metered	matches?	evidence
vidkraken.youtube.video.download	200 → COMPLETED in 5 s	jNQXAC9IVRw ("Me at the zoo", 19 s), format 360	$0.25/GB, 20 MB min ⇒ 0.02 GB	+20 MB, +1 download	✅	fileSize 475,958 B billed at the 20 MB floor; bandwidth_mb.used 1,123,936 → 1,123,956
vidkraken.youtube.audio.download	200 → COMPLETED in 5 s	same video, format audio	same	+20 MB, +1 download	✅	fileSize 252,182 B; 1,123,956 → 1,123,976
vidkraken.youtube.video.clip	200 → COMPLETED in 5 s	same video, 0–5 s, 360	same	+20 MB, +1 download	✅	fileSize 220,975 B; 1,123,976 → 1,123,996
vidkraken.youtube.download.job.status	200	jobId from the row above	free	no meter moved	✅	polled 2× per job, balances unchanged
vidkraken.youtube.video.detail	200 → success in 0 s	jNQXAC9IVRw	1 info request	+1 info	✅	info.used 11,339 → 11,341 across the two info rows (meter lags the response by a few seconds)
vidkraken.youtube.video.audio_tracks	200 → success in 6 s	omW5PrTMz-c (has dubbed tracks), includeAudioTracks: true	1 info request	+1 info	✅	same +2 total for the two info rows
vidkraken.youtube.info.job.status	200	jobId from the row above	free	no meter moved	✅	balances unchanged
vidkraken.account.usage	200	—	free	no meter moved	✅	this is the probe

Reconciliation of the sweep: bandwidth_mb.used 1,123,936 → 1,123,996 = 60 MB = 3 × 20 MB floor ✓; download_count 5,966 → 5,969 = 3 ✓; info 11,339 → 11,341 = 2 ✓ (the sweep also called POST /list-channel once, moving channel_list.used 1,180 → 1,181; that route was subsequently dropped from the listing). The account's client_download meter moved during the run (281,870 → 281,886) from unrelated concurrent traffic on this production account; no listed route touches that meter.

Notes on price observation: all three download test targets are tiny on purpose (sub-MB files) and therefore settle at the 20 MB floor — the floor is the observed charge. A download larger than 20 MB was not run in this sweep; the "actual file size" half of the rule is documented (OpenAPI info.description, pricing page), not observed here. There are no deliberate-miss targets. Expired/foreign job ids answer 404 {"error":"Download job not found"} and 404 {"error":"Job not found or expired"} respectively (observed 15:12:46 UTC).

Second sweep, 15:15 UTC, via scripts/catalog_verify.py vidkraken: PASS on every row (http 200; the run predates dropping the channel row, so it covered 9 rows of which the listed 8 are a subset). Its account-level deltas are not reported as meter evidence because the same account was serving unrelated traffic at the time (download_count moved by 5 where the sweep submitted 3).

Validation:

$ uv run --frozen python scripts/catalog_validate.py
OK — 97 provider file(s), 3256 endpoint(s), 0 error(s), 0 warning(s)
$ uv run --with pytest-xdist pytest -n auto -q
3612 passed, 6 skipped, 1 failed (run 1: test_the_plugin_skill_is_not_stale — fixed by regenerating the SKILL.md copies;
run 2: tests/test_maintenance.py::test_real_serve_path_can_query_database_after_pre_serve_maintenance —
passes when run alone: `pytest tests/test_maintenance.py tests/test_plugin.py` → 50 passed; flaky under -n auto, unrelated to this change)

Full documented surface map

The source of truth is the 6-path OpenAPI 3.1 document at https://vidkraken.com/openapi.yaml (plus one outbound webhook).

documented operation	decision
POST /download	Catalogued as three rows — youtube.video.download (360p–1080p MP4), youtube.audio.download (format audio: the API default and the cheapest tier), youtube.video.clip (startTime/endTime trim). The language (dubbed audio track) and webhookUrl options are inputs on those rows rather than separate rows.
GET /download/{jobId}	Catalogued — kind: utility poll target of the file-level async descriptor.
POST /info	Catalogued as two rows — youtube.video.detail (title + duration, the free-of-bandwidth pre-flight) and youtube.video.audio_tracks (includeAudioTracks: true).
GET /info/{jobId}	Catalogued — kind: utility poll target of the /info async override.
POST /list-channel	Excluded — channel video listing is better served by the dedicated YouTube data providers already on youtube.channel.videos.
GET /me	Catalogued — account.usage, the probe.
webhook download.finished	Excluded — an outbound callback, not a callable route; surfaced as the webhookUrl input.
POST /client-download (named in the spec's billing table; no published path)	Excluded — account add-on, not self-serve.

Capability mapping

• Reused: youtube.video.detail (POST /info — note it returns title + duration only, no stats; the row's summary and note say so. If reviewers would rather keep that id for stat-bearing providers, a narrower proposed id such as youtube.video.preflight is fine by us) and account.usage.
• Proposed (nothing on the youtube platform yields the media file today): youtube.video.download, youtube.audio.download, youtube.video.clip, youtube.video.audio_tracks, plus the two utility ids youtube.download.job.status / youtube.info.job.status.
• We are not aware of another provider in the catalog with an unmapped endpoint doing these download jobs.

How it was tested

Live sweep with our own key as above; scripts/catalog_verify.py vidkraken PASS on every row; scripts/catalog_validate.py exit 0 over the whole catalog; full pytest suite (result above).

Checklist

• uv run --with pytest-xdist pytest -n auto -q passes locally
• Added or updated tests for the change (provider added to test_every_provider_is_registered and the key-provider offerable loop)
• Updated the relevant docs/context/ fragment — data-only vendor listing; left to the maintainer half per docs/VENDORS.md
• No secrets in the diff (keys, tokens, .env values)

🤖 Generated with Claude Code

https://claude.ai/code/session_01SoRYeRXZeWQWWjdmFzBdhM