Magic Hour Documentation Audit

Magic Hour's API docs are unusually agent-friendly on the surface — llms.txt and llms-full.txt both resolve, every page serves clean .md, there's a published OpenAPI spec, a mock server, and an MCP server — but the reference index contradicts the spec, and the billing pages contradict the live pricing page in both directions.

1. API Reference index lists wrong paths for all three Files endpoints (critical)

Location: https://docs.magichour.ai/api-reference/overview

Problem: The "Files" section of the API Reference overview lists:

• POST /v1/files/generate-upload-urls — Generate asset upload URLs
• GET /v1/files/:id/face-detection — Get face detection details
• POST /v1/files/face-detection — Detect faces in an asset

The published OpenAPI spec (https://docs.magichour.ai/api-reference/openapi.json) and the endpoint pages themselves use entirely different paths: POST /v1/files/upload-urls, GET /v1/face-detection/{id}, and POST /v1/face-detection. The generate-asset-upload-urls page repeatedly shows https://api.magichour.ai/v1/files/upload-urls in its cURL/PHP/Java samples — none of the three paths printed on the overview page exist in the spec.

Consequence: The overview is the page both humans and AI agents use to enumerate the API surface. Anyone who constructs a request from the index — instead of clicking through to each endpoint page — calls a nonexistent path and gets a 404. An agent that cross-references the index against the spec sees three endpoints that appear in one source and not the other, and fails silently or hallucinates a reconciliation.

The fix: Correct the three Files entries on /api-reference/overview to match the OpenAPI paths (/v1/files/upload-urls, /v1/face-detection, /v1/face-detection/{id}), and generate the index from the spec so it can't drift again.

2. Billing docs contradict the live pricing page on prices, credits, and credit packs (critical)

Location: https://docs.magichour.ai/billing/overview and https://docs.magichour.ai/billing/subscription-pricing

Problem: The docs say Creator is "$15/mo or $10/mo (yearly)" with "10,000 credits per month (120,000/year)" and Pro is "$45/mo or $30/mo (yearly)" with "30,000 credits per month (360,000/year)". The live https://magichour.ai/pricing page charges Creator $19/mo ($144 billed annually) with 144,000 credits/year, and Pro $39/mo ($300 billed annually) with 300,000 credits/year. Every Creator and Pro number disagrees, in both directions: the docs undersell Creator's price and credits, and oversell Pro's price and credits by $60/year and 60,000 credits. Credit packs disagree too: docs say "1,000 credits per pack, $3.00 per pack ($0.003 per credit)"; the pricing page sells packs at "$1 = 400 credits" ($0.0025/credit) in 4,000/12,000/32,000 sizes with no 1,000-credit option.

Consequence: Developers estimating API costs from the billing docs — the pages written specifically for that purpose — budget against prices and credit allowances that don't exist. A team sizing a Pro plan from the docs expects 360,000 credits for $360 and actually gets 300,000 for $300; anyone modeling overage costs uses a per-credit price 20% too high and a pack size that isn't sold. An agent asked "what does Magic Hour cost" has two authoritative-looking sources with irreconcilable numbers.

The fix: Sync /billing/overview and /billing/subscription-pricing (plans, yearly totals, credit amounts, and credit packs) with the live pricing page, and add a review step so pricing changes update the docs in the same release.

3. 429 is documented as an error, but no API rate limit is documented anywhere (significant)

Location: https://docs.magichour.ai/get-started/quick-start (HTTP Error Codes table); https://docs.magichour.ai/changelog (2026-06-08 entry)

Problem: The quick start's error table documents 429 Too Many Requests — You are sending requests too quickly - retry with exponential backoff, but no page states what the limit is: no requests-per-second, per-minute, or concurrent-job numbers for the API. The only concurrency numbers in the entire docs are in the changelog (Free 1 / Creator 3 / Pro 5 / Business unlimited), and that entry explicitly disclaims them: "Concurrency limits apply to web app generations only—API usage does not count toward this limit."

Consequence: Developers building batch pipelines — the exact use case the Integration Overview markets ("Process large batches of media without manual intervention", "Handle high-volume generation") — cannot size their throughput or design backoff correctly. They discover the limits by tripping them in production. Agents can't answer "how many jobs can I submit in parallel" from these docs at all.

The fix: Publish an API rate-limits section (request limits and any per-plan concurrent-job caps) in the API reference, and link the 429 row of the error table to it.

4. canceled job status has no webhook event and no documented cancellation flow (significant)

Location: https://docs.magichour.ai/integration/webhook/event-types; https://docs.magichour.ai/api-reference/video-projects/get-video-details

Problem: The Get video/image/audio details endpoints document six statuses, including "canceled — user canceled". The Webhook Event Types reference documents only started/completed/errored events per media type — the word "cancel" does not appear on the page, and there is no video.canceled/image.canceled event. Nowhere in the reference — including the OpenAPI spec's 33-path inventory captured in the evidence, which contains no cancel path — is a cancellation endpoint documented, so the docs never explain how a job comes to be canceled or how an integration finds out.

Consequence: The docs push production integrations toward webhooks over polling ("Use create() with webhooks or background polling for production apps"). A webhook-only integration whose job is canceled from the web dashboard never receives any event: the job silently terminates and the developer's state machine waits forever. Developers must rediscover polling just to catch this one status.

The fix: State explicitly on the event-types page that cancellation does not emit a webhook (or add a *.canceled event), and document on the status reference how jobs get canceled and how to detect it.

5. OpenAPI spec's own description points to legacy, redirecting URLs (minor)

Location: https://docs.magichour.ai/api-reference/openapi.json (info.description)

Problem: The spec's description says "Webhook documentation can be found here" and "generate your API key here". Both are legacy URLs that 308-redirect (to docs.magichour.ai/webhook-reference and magichour.ai/developer respectively), while every docs page sends users to https://magichour.ai/developer?tab=api-keys instead.

Consequence: The spec is exactly what agents and SDK generators ingest first. Redirecting, out-of-date links in its description signal drift between the spec and the docs, and the API-key URL mismatch (settings/developer vs developer?tab=api-keys) makes tooling-generated getting-started text disagree with the human docs.

The fix: Update info.description to the current canonical URLs used elsewhere in the docs.

6. Python SDK install command inconsistent across tutorials (minor)

Location: https://docs.magichour.ai/get-started/quick-start vs https://docs.magichour.ai/integration/first-integration

Problem: The Quick Start says pip install magic_hour; the First Integration tutorial says pip install magic-hour. pip normalizes both to the same package, but the docs never say so, and the npm package is magic-hour while the import is magic_hour.

Consequence: Harmless at install time, but a small trust tax: developers (and agents diffing the two tutorials) see two different package names for the same SDK and must verify they're identical. Pinning tools and lockfile diffs will show whichever normalized form pip chose.

The fix: Pick one canonical form (PyPI's magic-hour) and use it in every install snippet.

What they do well

• Best-in-class agent surface: llms.txt + llms-full.txt, every page served as clean .md, a published OpenAPI spec, and an MCP server for editor integration.
• A documented SDK mock server for credit-free development, plus a dated, honestly-caveated observed processing-times page (p50 per endpoint).
• Webhook security done right: HMAC-SHA256 verification with exact header names, timestamp tolerance guidance, and multi-language verification code.

Top 3 recommendations

1. Generate the API Reference overview index from openapi.json so listed paths can never diverge from the spec.
2. Sync all billing pages (plan prices, credit amounts, credit packs) with the live pricing page and add pricing-change review to the release process.
3. Publish concrete API rate/concurrency limits and document the cancellation gap in webhook coverage.